******************************************************************************* WRAPI CORRECTIVE SERVICE INSTRUCTIONS FILE ******************************************************************************* This package was generated to provide the current service for the IPFAF Workstation APIs (WRAPI) associated with the updates for the New Password support, IODM Annotation support, and the IODM Dynamic TCPIP support. Hence neither of those fixes should be applied after this fix. In addition, you must apply the appropriate Host APARs/PTFs: for IODM Dynamic TCPIP support (prereq the IODM Annotation) - PQ18457/UQ21705 PQ18173/UQ21707 for IODM Annotation support - PQ21304/UQ26053 PQ21305 PQ21306/UQ26058 for Host RAPI - PQ26467/UQ34317 PQ14116/UQ17752 PQ35233/UQ39932 (for CICS) PQ35247/UQ44360 (for IMS) for Host API BASE - PQ23295/UQ26248 for Host API FEATURE - PQ21377/UQ26247 PQ27166/UQ31077 PQ28539/UQ32307 ******************************************************************************* The following are the instructions for applying the code: To install this package: 1) IPFAF and IODM must be at the Version 3.1 Level with Annotation Support and Dynamic TCPIP Support fixes installed on IODM. 2) This fix is simply a replacement of the WRAPI files which are ON OS/2 ------- EYP.H (Header file in INCLUDE path) EYPAPI.INI (Customization file in EYPINIFILE setting) EYPOAPI.LIB (Library file in LIB path) EYPOAPI.DLL (Executable in LIBPATH) ON WINDOWS ---------- EYP.H (Header file in INCLUDE path) EYPAPI.INI (Customization file in EYPINIFILE setting) EYPWAPI.LIB (Library file in LIB path) EYPWAPI.DLL (Executable in PATH setting) 3) Download the package from the bulletin board or FTP site into a temporary directory 4) PKUNZIP the package by issuing: PKUNZIP2 EYPOAPI.ZIP (on OS/2) PKUNZIP EYPWAPI.ZIP (on WINDOWS) 5) Replace the original WRAPI files with the new ones by simply copying the new files into the directories where the old files were stored. 6) Recompile any programs which were written to the old WRAPI. NOTE the annotation update changed the FafSessionConnect() call to include the additional IODM connection information parameters. Also the FAFCONNECTPARMS structure was changed and appropriate changes must be made when referencing it. 7) If desired, instead of replacing the EYPAPI.INI file, simply add the new INI parameter(s) to the old EYPAPI.INI file currently installed. The new INI parameters are - DefDocUsingId = 1 (if pszOAMName specifies a DOCID in FafDefineStoredDoc call) RequireIPFAF = 1 (if IPFAF connection required) IodmLOCK = LOCK,01 (IODM CICS Tran name for Lock) IodmSTOROBJU = STOU,01 (IODM CICS Tran name for StorObjU) ******************************************************************************* New details of the CICS TCPIP Listener data The following describes the data which is sent to the host CICS TCPIP Listener program by the WRAPI calls. The IODM information has not been changed by this update, but is included for completeness. This information is needed for those customers who are supplying a security exit for the CICS TCPIP Listener. IODM ---- Bytes 0 - 3 Host Transaction name to start (i.e. "SRET") Byte 4 A comma (i.e. ",") Bytes 5 - 6 A flag to indicate WRAPI ("01") versus IWPM ("00") (i.e. "01") Bytes 7 - 14 The IODM Terminal Id (max 8 characters) padded with blanks (i.e. "TERMID ") Bytes 15 - 22 The IODM User Id (max 8 characters) padded with blanks (i.e. "USERID ") Bytes 23 - 30 The IODM Password (max 8 characters) padded with blanks (i.e. "PASSWORD") Bytes 31 - 38 The New IODM Password (max 8 characters) padded with blanks. This will only be sent on the "STAT" transaction which is sent when a FafSessionConnect() API is called. In all other cases, these bytes are not sent. (i.e. "NEWPSWD ") IPFAF ----- Bytes 0 - 3 Host Transaction name to start (i.e. "RAP1") Byte 4 A comma (i.e. ",") Bytes 5 - 6 The FAF Application Id as a number (NOT EBCDIC) (i.e. 01) Bytes 7 - 14 The FAF User Id (max 8 characters) padded with blanks (i.e. "USERID ") Bytes 15 - 34 The FAF Password (max 20 characters) padded with blanks (i.e. "PASSWORD ") Note - on IODM, the new password is specified on the "STAT" transaction and provided to the CICS TCPIP Listener security exit. If successful, this new password will be sent in the password field on subsequent transactions. on IPFAF, the new password is not sent to the CICS TCPIP Listener security exit, but instead can be changed via the exit called by the "RAP1" transaction. If successful, the new password will be sent in the password field to the CICS TCPIP Listener. Hence the "RAP1" user exit must also update the password security field checked by the CICS TCPIP Listener security exit. ******************************************************************************* New or Changed WRAPI functions (see EYP.H) FafSessionConnect -- changed Now has IODM termid, userid, password, and newpassword fields for dynamic TCPIP connectivity. FafCreateFEAKey() -- new Used to create a FEA Key which is needed to call the new functions FafLockDocAnnotation(), FafUpdateDocAnnotation(), and FafUpdateItemLock(). The input required is -- Folder Token Document ID Document Version The output is written into a FEAKEY structure whose address is provided by the user. FafGetDocument() -- changed The COPYTYPE parameter now allows you to use COPY_ANNOTATION_INDEX to receive the document annotation index. FafGetDocAndOverlays() -- changed The DOCOVERSTRG structure has been changed to allow you to receive the annotation index and object. FafLockDocAnnotation() -- new Allows the user to lock a document. This is required to update or create an annotation. FafStoreDefinedDoc() -- changed The LOCCNTL structure has been changed to allow the user to also store an annotation object with the document. FafUpdateDocAnnotation() -- new Allows the user to change or create an annotation. FafUpdateItemLock() -- new Allows the user to change the lock state of a document. New WRAPI error codes -- FAF_RC_ANNOTATION_MISSING 2026 FAF_RC_INVALID_ANNOTATION_INDEX 2027 FAF_RC_IPFAF_NOT_AVAILABLE 3010 FAF_RC_INVALID_ODM_USERID 3011 FAF_RC_INVALID_ODM_PASSWORD 3012 FAF_RC_INVALID_ODM_TERMID 3013 ******************************************************************************* The following is a list of the APARs that have been put into this package: PQ35231 FafSessionConnect Application ID code (ApplidCD) includes number 0 now to keep consistent with the host setting. PQ35232 FafGetWorkItems cursors didn't work because the information of Assigned and Processing Employee was NULL, but required by host GETWORK IPFAF API. PQ39465 Host Session index was above upper bound MAX_HOST_SESSIONS of the table. PQ39466 FafQueryOutcome ten items were not returned to the OUTCOMEINFO structure, but did exist on the host. PQ39467 FafGetDocument bypasses the host return/reason code 0 FFFF 0001 and returns WRAPI client warning code 1500 to application for the case that document stored in Optical Storage Device and not received by WRAPI. PQ29873 FafFindWorkByUnit cursors failed with NULL ASGNEMPL and PROCEMPL. PQ31198 (1) FafFindWqAsgnsByUser continuing search criterion was incorrectly changed when further issuing UASGNACT Host call. (2) FafFindWqAsgnsByUser cursor failed with missing QPTYSRCH. PQ31238 (1) FafDefineDocument UserData field was not copied to DB2 table. (2) FafStoreDocument returned DOCID had the StoreSite and TimeStamp values reversed. (3) FafDefineStoredDoc DOCNAME was used to define new document, but really should use the DOCID instead. Add INI option in EYPAPI.INI file to use DOCID instead of DOCNAME. (4) FafFindNotes cursors failed with NULL StartTime and EndTime. ******************************************************************************* Documentation updates: (1) FafUpdateDocAnnotation annotation object length was not specified when using a buffer or a file, but required by WRAPI. Updates: IP FAF WRAPI Programming Reference (SC34-3112-01) Version 3 Release 1 Chapter 6. Document Management (IODM) Interfaces Application Programming Interfaces FafUpdateDocAnnotation Parameters Page 105. Update the description of parameter pLocOpts: This API uses the values defined for annotation object length and annotation buffer pointer or file name. If an annotation exists, the annotation object length must be specified whether using an annotation buffer or annotation file. If no annotation exists, set the annotation information to NULL. Either this parameter or the pDocOverlays parameter must be specified. (2) FafFindPendDocSingle data type of parameter usUserStatus was inconsistent. Updates: 1. IP FAF WRAPI Application Programmer's Guide (SC34-3113-01) Version 3 Release 1 Chapter 10. Pending or Temporary Document Management Interfaces Retrieving Pending or Temporary Document Information Page 35. Add the description in the second paragraph: When the FafFindPendDocSingle API is used, the parameter usUserStatus in the TEMPDOCINFO return structure must be numeric. This parameter may be stored to host by another API before this call is invoked. 2. IP FAF WRAPI Programming Reference (SC34-3112-01) Version 3 Release 1 Chapter 5. Document Management Interfaces Application Programming Interfaces FafFindDocuments Parameters Page 63. Remove the last sentence from the description of parameter pUserStatus: If this parameter is supplied, it must be numeric. 3. IP FAF WRAPI Programming Reference (SC34-3112-01) Version 3 Release 1 Chapter 12. Data Structures and Definitions TEMPDOCINFO (Pending Document Information Structure) Page 230. Update the description of parameter usUserStatus: A user-defined status which can be used to search for documents via the FafFindDocuments or FafCountDocuments APIs. Note: The returned value which was stored by another API must be numeric. (3) Add INI file description for FafDefineStoredDoc parameter option, see the third item of APAR PQ31238 listed above. Updates: IP FAF WRAPI Application Programmer's Guide (SC34-3113-01) Version 3 Release 1 Chapter 2. Installation and Customization Initialization File Customization Page 8. Add the description between parameters RequireIPFAF and TimeOutTCPIP: DefDocUsingId FafDefineStoredDoc API option to specify OAMName to be DOCID versus DOCNAME. The default is DOCNAME (0). Recommend specifying the DOCID option. When DOCID is used as OAMName, the CreateSite of the document is consistent with IODM's name of the document. (4) FafFindWqAsgnsByUser parameter AsgnStatus and its description were missing. Updates: IP FAF WRAPI Programming Reference (SC34-3112-01) Version 3 Release 1 Chapter 10. WorkFlow Management WorkQueue Assignment Application Programming Interfaces FafFindWqAsgnsByUser Parameters Page 146. Add missing parameter in Format and description between parameters pRoutingUnit and pWrkAsgnCrsr: Format FafFindWqAsgnsByUser(hFSession,pszUserid,pRoutingUnit,AsgnStatus, pWrkAsgnCrsr,usToBeRet,pFCallBack,pFR) AsgnStatus STATSRCH - input WorkQueue Assignment Status. Use this parameter to set options for assignment entries that are inactive, active, or both. The options are as follows: * STAT_INACTIVE_ONLY (default) * STAT_ACTIVE_ONLY * STAT_BOTH_ACTV_INACTV (5) IODM Bytes numbers for byte mapping were incorrect. Updates: IP FAF WRAPI Application Programmer's Guide (SC34-3113-01) Version 3 Release 1 Chapter 2. Installation and Customization Host Installation Page 3. Update the Byte(s) for ODM: The Object Distribution Manager CICS TCP/IP Listener receives: Byte(s) Description 0 - 3 Host CICS Transaction name to start (for example, SRET). 4 A coma (,). 5 - 6 A flag to indicate WRAPI (X'01') rather than ImagePlus Workstation Program (X'00'). 7 - 14 The Object Distribution Manager terminal ID (maximum of 8 characters) padded with blanks (for example, TERMID). 15 - 22 The Object Distribution Manager user ID (maximum of 8 characters) padded with blanks (for example, USERID). 23 - 30 The Object Distribution Manager password (maximum of 8 characters) padded with blanks (for example PASSWORD). 31 - 38 The new Object Distribution Manager password (maximum of 8 characters) padded with blanks (for example, NEWPSWD). This is sent only on the STAT transaction that is sent when a FafSessionConnect() API is called. In all other cases, these bytes are not sent. ******************************** end of file **********************************