Previous Topic
Table Of Contents
Parent Topic
Next Topic

The SWSAPCON Function

Related Topics

Web Server API Function Index

	May be used in Shadow/REXX
	May be used from Other REXX Interpreters
	High-level Language Interface

The REXX-language SWSAPCON built-in function can be used for APPC connections between the Shadow OS/390 Web Server for IMS and IMS v4.1 and above. A call to this function will connect to IMS, send a transaction for IMS to execute and receive the data from the executed transaction. The data received is in the format of the Message Output Descriptor (MOD) used by the application program which processed the transaction.

Upon return from the call, the following Rexx variables are populated with data:

APPC.STMTHDL	The statement handle for the interface call.
APPC.CONVID	The Conversation ID for the IMS APPC conversation.
APPC.OUTBUFF.0	The length of the data contained within the APPC.OUTBUFF.1 Rexx variable.
APPC.OUTBUFF.1	The returned Message Output Descriptor data. The output message contains the MOD data as well as a two byte length prefix. This variable contains the data, including any supplied trailing blanks.
APPC.RETCODE	The APPC Interface return code.
APPC.DATATYPE	The returned datatype.

SWSAPCON Syntax

The general form for a REXX-language invocation of SWSAPCON is:


   rc = SWSAPCON("Connection Type", ,
                 "Transaction Name", ,
                 "Transaction Name Length", ,
                 "Partner LU Name", ,
                 "Security Type", ,
                 "Transaction Data", ,
                 "Local LU Name", ,
                 "Mode Name", ,
                 "Symbolic Partner LU Name", ,
                 "Userid", ,
                 "Password", ,
                 "Security Profile", ,
                 "Data Type Sent", ,
                 "Message Length Sent", ,
                 "Synchronization Level")

Connection Type	Specifies the type of IMS transaction to execute IMS IMS Non-conversational transaction. IMSCONV IMS Conversational transaction. *Note:* Required parameter.
Transaction Name	Specifies the IMS Transaction Code *Note:* Required parameter.
Transaction Name Length	Specifies the length of the IMS Transaction Code *Note:* Required parameter.
Partner LU Name	Specifies the APPC LU Name for the IMS system *Note:* Required parameter.
Security Type	Specifies the type of security in use. NONE Specifies that no access security information is to be passed on the APPC Allocation request. SAME Specifies to use the userid and security profile (if present) from the allocation request that initiated the local program. The password (if present) is not used; instead, the userid is indicated as "already been validated". If the allocation request that initiated the local program contained no access security information, then access security information is omitted on this allocation request. PROGRAM Specifies to use the security information, provided by the local program, on the API call. The local program provides the information by means of the Userid, Password and Security Profile parameters. These values are passed exactly as specified (without folding the characters to upper case). *Note:* Required parameter.
Transaction Data	Specifies any data required by the application program in order to process the transaction. This would be data in the format of the Message Input Descriptor (without the LLZZ prefix). *Note:* Required parameter.
Local LU Name	Specifies the name of a local LU from which the caller's allocate request is to originate. This is provides the ability to associate a transaction request with a particular LU name. *Note:* Optional parameter. If used, it requires the use of Mode Name, Symbolic Partner LU Name, User ID, Password and Security Profile be coded.
Mode Name	Specifies the Mode name designating the network properties for the local LU Name. *Note:* Optional parameter. If used, it requires the use of Local LU Name, Symbolic Partner LU Name, User ID, Password and Security Profile be coded.
Symbolic Partner LU Name	Specifies the symbolic name representing the IMS APPC LU Name, Mode Name, Transaction Name. The symbolic destination name must match that of an entry in the side information dataset. If you specify any pass any of the parameters (Local LU Name, Mode Name or Transaction Name), these will override the information retrieved and used to initialize the the characteristics of the conversation. *Note:* Optional parameter. If used, it requires the use of Local LU Name, Mode Name, User ID, Password and Security Profile.
User ID	The Partner LU uses this value and the Password to validate the identity of the end user that initiated the request. *Note:* Optional parameter. If used, it requires the use of Local LU Name, Mode Name, Symbolic Partner LU Name, Password and Security Profile.
Password	The Partner LU uses this value and the User ID to validate the identity of the end user that initiated the request. *Note:* Optional parameter. If used, it requires the use of Local LU Name, Mode Name, Symbolic Partner LU Name, User ID and Security Profile.
Security Profile	Specifies additional security information that may be used to determine what partner programs the local program may access. *Note:* Optional parameter. If used, it requires the use of Local LU Name, Mode Name, Symbolic Partner LU Name, User ID and Password.
Data Type Sent	Specifies the action to take once the APPC Conversation is established. BUFFER Specifies that no additional data is to be sent to the Partner LU, and the data may be buffered until a sufficient quantity is accumulated. SENDFLSH Specifies that no additional data is to be sent to the Partner LU, and the data is to be sent immediately. SENDCONF Specifies that the data is to be sent immediately along with a request for confirmation. SENDPREP Specifies that the data is to be sent immediately along with send control of the conversation. SENDDEAL Specifies that the data is to be sent immediately along with a deallocation notification. *Note:* Optional parameter. If used, it requires that placeholders be specified for Local LU Name, Mode Name, Symbolic Partner LU Name, User ID, Password and Security Profile.
Synchronization Level	Specifies whether or not confirmation processing will be performed on this conversation. NONE No confirmation processing is required for this conversation. CONFIRM Confirmation processing is required for this conversation. *Note:* Optional parameter. If used, it requires that placeholders be specified for Local LU Name, Mode Name, Symbolic Partner LU Name, User ID, Password, Security Profile and Data Type Sent.

SWSAPCON Examples


 
     /*-------------------------------------------------------------*/
     /* initialize some system values                               */
     /*-------------------------------------------------------------*/
 
     address SWSSEND
     imsappc = 'P390.P392AIMS'
     imstran = 'NEONDISP'
     parms   = ''
 
     /*-------------------------------------------------------------*/
     /* execute the ims transaction                                 */
     /*-------------------------------------------------------------*/
 
     rc = swsapcon('ims',imstran,length(imstran),imsappc,'NONE',parms)
 
     /*-------------------------------------------------------------*/
     /* parse the output into usable variables                      */
     /*-------------------------------------------------------------*/
 
     pars.msg      = substr(APPC.OUTBUFF.1,1,79)
     pars.page     = substr(APPC.OUTBUFF.1,80,2)
     pars.index    = substr(APPC.OUTBUFF.1,82,2)
     pars.scroll   = substr(APPC.OUTBUFF.1,84,150)
 
     pars.area     = substr(APPC.OUTBUFF.1,234,380)
     pars.len      = 380
     pars.data     = ''
     do i = 1 to 10
       pars.part.i = substr(pars.area,4,15)
       pars.desc.i = substr(pars.area,19,20)
       pars.len    = pars.len - 38
       pars.area   = substr(pars.area,39,pars.len)
       pars.data   = pars.data||' '||pars.part.i||pars.desc.i
     end

Top