CICS Runtime Integration with Application List Transaction

ART for CICS enables you to use application list transaction (ALST) to manage multiple sessions. It is integrated with user plug-in to enable you to get and show application list.

Integration with User Plug-In

When ALST transaction is running by synchronous transaction servers (ARTSTRN/ARTSTR1), it calls user plug-in to get the application list.

For user plug-in, make sure

•	It is implemented in C language.

•	It is built as a dynamic shared library named libkixauthalst.so.

•	It provides a function entry called ARTKIX__GET_USER_ALST. For more information, see ARTKIX__GET_USER_ALST.

ARTKIX__GET_USER_ALST

Synopsis

int ARTKIX__GET_USER_ALST(ALST_INOUT_PARAM * alst)

Description

In terms of input, when calling ARTKIX__GET_USER_ALST, ART for CICS fills VERSION, USERID, and LISTSZ fields, and sets the RESERVED field to 0.

In terms of output, ARTKIX__GET_USER_ALST updates LISTSZ and fills APPLIST.

 

Table 7‑1 Input/Output Parameters

Field	Type	I/O Type	Description
VERSION	Integer, 4 bytes	Input	Version number. The current version is 1.
RESERVED	Integer, 4 bytes	Input	Reserved field. Must be binary zero.
USERID	Char, 8 bytes	Input	User ID who needs to get its application list.
LISTSZ	Integer, 4 bytes	Input and output	When using LISTSZ as input, it specifies the length of APPLIST, indicating how many applications that the application list can contain at most. Fill the application list in the address right after this field. See Listing 7‑1 for an example, which denotes that the application list can contain 128 applications at most. When using LISTSZ as output, ARTKIX__GET_USER_ALST returns the number of applications that are actually used.
APPLIST	Applications array	Output	List of applications to be authorized. Array length is specified in LISTSZ field; every array item is composed of seven sub-fields. • transid (4 bytes): Transaction ID of the application. This must be a valid transaction in ART for CICS. • sessid (8 non-blank bytes): Session ID. It should be unique for a user. • fnkey (1 byte): Reserved for future use. The value of function key associating with the application. This value uses ASCII encoding. • label (35 bytes): Business name of the application. • startupACLName (8 bytes): Startup ACL CICS program name. • termACLName (8 bytes): Reserved for future use. • reserved (3 bytes): Must be binary zero.

Listing 7‑1 C Definitions of ALST_INOUT_PRARM

typedef struct {

char transid[4];

char sessid[8];

char fnkey;

char label[35];

char startupACLName[8];

char termACLName[8];

char reserved[3];

} ALST_APPLICATION;

 

// Input & Output

typedef struct {

int version;

int reserved;

char userid[8];

int listsz;

ALST_APPLICATION applst[128];

} ALST_INOUT_PARAM;

 

Return Code

Return Code: 0 is success. -1 is failure.

COMMAREA Between DFHALST and Startup ACL

Listing 7‑2 is an example.

Listing 7‑2 Example of COMMAREA

01 COMM-ACL.

05 ACL-USERID PIC X(8).

05 ACL-TRANSID PIC X(4).

05 ACL-RETCODE PIC s9(8) comp-5.

05 ACL-RETMSG PIC X(1920).

05 ACL-MSGLEN PIC s9(8) comp-5.

05 FILLER PIC X(60).

 

Input

ALST fills following fields when DFHALST LINK ACL:

ACL-USERID

USERID of the user.

ACL-TRANSID

The transaction ID to be started.

Output

ACL fills following fields when ACL RETURN to ALST:

ACL-RETCODE

The return code (0 is success; -1 is failure).

ACL-RETMSG

If ACL-RETCODE=0, ACL-RETMSG contains initial input string that denotes how to call a transaction (the input string is the exact input that user types in 3270 terminal instead of the real 3270 data stream. ART for CICS will compose the 3270 data stream from the input string). The size of this field is 1920 bytes (padded with trailing spaces if needed).

If ACL-RETCODE=-1, ACL-RETMSG contains the detailed error message, which ALST shows it on terminal. The error message is 160 bytes long (padded with trailing spaces if needed).

ACL-MSGLEN

Length of the initial input string ACL-RETMSG.

If the value is zero, ART for CICS removes trailing spaces/binary zero from ACL-RETMSG.

If the value is non-zero, this value should be the size of the message (a positive integer less than or equal to 1920), and then ART for CICS uses this size to call the transaction.

FILLER

Reserved 60 characters for future use. It must be binary zeros.

API for Startup ACL

ARTKIX__SET_TRAN_INIT_STR

Synopsis

int ARTKIX__SET_TRAN_INIT_STR (char* pbuf, int size, char * aid)

Description

Set transaction input string just like you enter on a 3270 blank screen (ARTKIX__SET_TRAN_INIT_STR will convert this input string to 3270 data stream for you).

If you issue RECEIVE command after the call, RECEIVE can get the input data; if you do not issue RECEIVE command, the data stream is discarded when the transaction returns to ARTTCP.

pbuf

Input. The input string used to start the transaction. It should be ASCII encoded other than EBCDIC.

For example, If you type XXXX abcd1234 in 3270 console, XXXX is the transaction ID to be started, and abcd1234 is the input message. Therefore, XXXX abcd1234 should be passed with pbuf.

size

Input. Length of the input string.

aid

Input. The Action ID. It should be ASCII encoded other than EBCDIC. If aid is NULL, the aid DFHENTER will be used by default.

Return Code

Return Code: 0 is success. -1 is failure.

ARTKIX__GET_TRAN_OUT_STR

Synopsis

int ARTKIX__GET_TRAN_OUT_STR(char* pbuf, int size)

Description

Get output data string that the last SEND verb (in the transaction) sends. You do not need to decompose this output string to 3270 data stream as ARTKIX__GET_TRAN_OUT_STR will do it for you.

pbuf

Output. Returns output data string, which is just like the data string that 3270 terminal displays.

size

Input. Max length of the buffer that pbuf points.

Return Code

Return Code: Returning the length of the received buffer denotes success. Returning -1 denotes failure.

See Also

"Implementing Using Multiple Session Management" in Oracle Tuxedo Application Runtime for CICS User Guide