Interfacing with a Non-TCP Requester › Interfacing with a Non-Terminal Control Process Requester With an IPCO Library

Interfacing with a Non-Terminal Control Process Requester With an IPCO Library

A non-TCP requester is an entity program that resides outside the boundaries of the AEF. As a result, the Terminal Control Process (TCP) that usually monitors all terminal activity generated by traditional requesters has no control over the execution of non-TCP requesters.

For a non-TCP requester to establish communication with the AEF environment, a set of routines is developed to form an interface. This interface is delivered as a library named IPCO. It can be found in the subvolume where the Implementation Toolset is located. The IPCO interface allows a user-written non-TCP requester to communicate to any of the CA Gen application servers that typically do not contain any user interface (like the Blockmode Commandline Nodisplay applications).

The IPCO library contains the following routines:

• INITIALIZE^IPC—Sets up internal data structures
• DECODE^MSGRT^IPC—Verifies call to MSGRT server
• DECODE^SERVER^IPC—Decodes information from IEFSRV
• PREPARE^SERVER^IPC—Set attributes within AEF data structures

The following sections provide more information about each of these routines.

Note: Two sample programs are provided to assist you in understanding the use of the procedure calls. You can find the source in the NTCPR1S and NTCPR2S files that are available in the subvolume where the IT is located.

INITIALIZE^IPC Routine—Set Up Internal Data Structures

The non-TCP requester calls the INITIALIZE^IPC routine once before calling any of the other procedures. This routine sets up internal data structures that will be used to communicate with the application servers.

Usage

The syntax of the INITIALIZE^IPC call is:

CALL INITIALIZE^IPC	(trancode                      !input
                           ,options                        !input
                           ,display^terminal               !input
                           ,display^terminal^type          !input
                           ,display^terminal^subtype       !input
                           ,debug^terminal                 !input
                           ,debug^terminal^type            !input
                           ,debug^terminal^subtype         !input
                           ,userid                         !input
                           ,printer^name                   !input
                           ,flag^switch^message            !input
                           ,flag^test                      !input
                           ,flag^trace                     !input
                           ,trace^level                    !input
                           ,MAX^REPLY^LENGTH               !input
                           ,ipc^interface                  !output
                           ,write^length                   !output
                           ,error^code                     !output
                           ,error^subcode );               !output

Description

The INITIALIZE^IPC routine performs the following tasks.

• Verify a valid terminal type
• Verify a valid user's buffer size
• Compute the length of the buffer used later by SERVERCLASS_SEND

After the call to INITIALIZE^IPC routine is complete, a call to MSGRT must follow. This call must use the IPC^INTERFACE buffer to pass all the information necessary to obtain the name of the server class that will satisfy the initial request.

Parameters

trancode

I/O: Input

STRING:ref:*

Identifies the transaction ID used to start the application. Only the first eight bytes of the ID are used to populate the transaction code in the internal data structure.

options

I/O: Input

STRING:ref:*

Defines clear screen options such as RESET or RESTART. The options field can be up to 80 bytes in length, which can include spaces.

display^terminal

I/O: Input

INT:ref:*

Identifies the name of the terminal in external format. Only local terminal names of up to 16 bytes in length are allowed.

display^terminal^type

I/O: Input

STRING:ref:*

Identifies a one-byte field denoting the terminal type. The following values are valid for this field.

1

Indicates 6530 terminal types.

2

Indicates 3270 terminal types.

display^terminal^subtype

I/O: Input

INT:ref:*

Identifies a one-byte field denoting the terminal attributes. The following values are valid for this field.

1

Indicates non-extended attributes.

2

Indicates extended attributes.

debug^terminal

I/O: Input

STRING:ref:*

Identifies a one-byte input value that is no longer used.

debug^terminal^type

I/O: Input

INT:ref:*

Identifies a one-byte input value that is no longer used. Must be set to 0.

debug^terminal^subtype

I/O: Input

INT:ref:*

Identifies a one-byte input value that is no longer used. Must be set to 0.

userid

I/O: Input

STRING:ref:*

Identifies the user running the application. Values up to 16 bytes in length are allowed.

printer^name

I/O: Input

STRING:ref:*

Identifies the name of the printing device. Values up to 36 bytes in length are allowed.

flag^switch^message

I/O: Input

INT:ref:*

Identifies a one-byte input value that is no longer used. Must be set to 0.

flag^test

I/O: Input

INT:ref:*

Identifies a one-byte input value that is no longer used. Must be set to 0.

flag^trace

I/O: Input

INT:ref:*

Identifies a one-byte input value that is no longer used. Must be set to 0.

trace^level

I/O: Input

INT:value

Defines an input value that exists for internal use only. Must be set to 0.

max^reply^length

I/O: Input

INT:value

Identifies the size of the buffer interface. The minimum size of this field must be equal to or greater than 8 K bytes and less than or equal to 32 K bytes.

ipc^interface

I/O: Output

STRING.EXT:ref:*

Identifies a field that contains all the configuration parameters that are to be forwarded to the application servers.

write^length

I/O: Output

INT:ref:*

Identifies a field that returns the length of the buffer being sent back to the calling procedure.

error^code

I/O: Output

INT:ref:*

Identifies a field that returns a value showing the state of the call after it completes.

1

Indicates an invalid buffer size (less than 8 K).

2

Indicates an invalid terminal type.

-1

Indicates no errors.

error^subcode

I/O: Output

INT:ref:*

Identifies a field always returning a value of -1.

Example

! set the initial information !
   CALL get^initial^info( pathmon^name
                         ,pathmon^name^len
                         ,trancode
                         ,options
                         ,display^terminal
                         ,display^terminal^type
                         ,display^terminal^subtype
                         ,flag^test
                         ,debug^terminal
                         ,debug^terminal^type
                         ,debug^terminal^subtype
                         ,flag^trace
                         ,trace^level
                         ,flag^switch^message
                         ,userid
                         ,printer^name );
! Initialize IPC info
   CALL INITIALIZE^IPC( trancode
                       ,options
                       ,display^terminal
                       ,display^terminal^type
                       ,display^terminal^subtype
                       ,debug^terminal
                       ,debug^terminal^type
                       ,debug^terminal^subtype
                       ,userid
                       ,printer^name
                       ,flag^switch^message
                       ,flag^test
                       ,flag^trace
                       ,trace^level
                       ,MAX^REPLY^LENGTH
                       ,buffer
                       ,write^length
                       ,error^code
                       ,error^subcode );
! Check for errors
  IF error^code <> -1 then
            call error^routine;

DECODE^MSGRT^IPC Routine—Verify Call to MSGRT Server

Use the DECODE^MSGRT^IPC routine after each call to MSGRT. You can use this routine to obtain information about the server class name responsible for the execution of the current transaction ID.

Usage

The syntax of the DECODE^MSGRT^IPC call is:

CALL DECODE^MSGRT^IPC( ipc^interface                   !input
                      ,reply^code                      !output
                      ,trancode                        !output
                      ,trancode^len                    !output
                      ,server^class^name               !output
                      ,server^class^len                !output
                      ,write^length                    !output
                      ,error^code                      !output
                      ,error^subcode );                !output

Description

The DECODE^MSGRT^IPC routine verifies if the call to the MSGRT server is successful. It also obtains routing information through the transaction ID and the server class name parameters.

Parameters

ipc^interface

I/O: Input

STRING.EXT:ref:*

Identifies an interface buffer that contains all the configuration parameters, which are forwarded to the MSGRT server.

reply^code

I/O: Output

INT:ref:*

Indicates the output value.

0

Indicates no error occurred.

1

Indicates an invalid terminal type was passed to the MSGRT within the interface buffer.

trancode

I/O: Output

STRING:ref:*

Identifies a value representing the transaction ID from the TMT table.

trancode^len

I/O: Output

INT:ref:*

Indicates the length (in bytes) of the transaction ID returned in the trancode.

server^class^name

I/O: Output

STRING:ref:*

Identifies the name of the server class found in the TMT table that satisfies the incoming transaction ID.

server^class^length

I/O: Output

INT:ref:*

Identifies the length (in bytes) of the server class name.

pathsend^write^length

I/O: Output

INT:ref:*

Identifies the length of the data returned by MSGRT.

error^code

I/O: Output

INT:ref:*

Indicates a value showing the state of the call when it completes.

-1

Indicates no errors.

4

Indicates that an invalid transaction code was sent to the MSGRT server.

error^subcode

I/O: Output

INT:ref:*

Identifies a field always returning a value of -1.

Example

!Send the data buffer to the MSGRT server using the SENDSERVER_CLASS_call
server^class^name':='"MSGRT";
server^class^name^len:=5;
error := SERVERCLASS_SEND_( pathmon^name
                           ,pathmon^name^len
                           ,server^class^name
                           ,server^class^name^len
                           ,data^buffer
                           ,write^length
                           ,MAX^REPLY^LENGTH
                           ,count^read
                           ,timeout
                           ,flags
                           ,^ScSendOpNum );
IF error <> FEOK THEN
call error^routine;
CALL DECODE^MSGRT^IPC( data^buffer
                      ,reply^code
                      ,trancode
                      ,trancode^len
                      ,server^class^name
                      ,server^class^name^len
                      ,write^len
                      ,error^code
                      ,error^subcode );
! Check for errors
  IF error^code <> -1 then
            call error^routine;

DECODE^SERVER^IPC Routine—Decode Information from IEFSRV

The user program must call the IEF^DECODE^SERVER^IPC routine after every call to IEFSRV. This routine decodes (translates) information from IEFSRV and writes it to a buffer.

Usage

The syntax of the DECODE^SERVER^IPC call is:

CALL DECODE^SERVER^IPC( ipc^interface                  !input
                       ,reply^code                     !output
                       ,flag^change                    !output
                       ,flag^abort^transaction         !output
                       ,server^class^name              !output
                       ,server^class^len               !output
                       ,data^message                   !output
                       ,data^length                    !output
                       ,diagnostic^message             !output
                       ,diagnostic^length              !output
                       ,write^length                   !output
                       ,error^code                     !output
                       ,error^subcode );               !output

Description

A non-zero value in the reply^code parameter can imply any one of the following:

• An invalid terminal type was passed to the application server in the interface buffer.
• There was an error during an I/O operation involving the overflow file.

The IEFREQ requester has the limitation of handling only up to 8 K of data. When this happens, the source server writes the remaining data to a temporary file called the overflow file. An overflow file is used when a server is unable to pass the entire data buffer back to the requester. The server then passes the information back to the requester including the name of this temporary file. The IEFREQ requester forwards this information to the target server, which also reads the overflow file to obtain the remaining information.

A value of 0 in the flag^change parameter implies that a reply should be forwarded to you. In that case, the data^message buffer will receive the data returned from the server. The data^length parameter will have the length, in bytes, of this buffer. If a diagnostic message is present, it will be placed in the diagnostic^message buffer. Diagnostic^length has the length of the diagnostic^message buffer.

If the flag^change parameter is set to 1, then the server^class^name will have the name of the server to which the reply should be forwarded. Server^class^length has the length, in bytes, of the name of the server, and pathsend^write^length contains the size of the data that should be passed to the next server class.

Also, the flag^abort^transaction will be set if the server detects a problem.

Parameters

ipc^interface

I/O: Input

STRING.EXE:ref:*

Identifies a buffer interface that receives data returned from the application server.

reply^code

I/O: Output

INT:ref:*

Returns 0 if no error occurs during the call.

flag^change

I/O: Output

INT:ref:*

1

Indicates that a dialog flow will occur to another server class. In this case, server^class^name contains the name of the new server class.

0

Indicates that no dialog flow will take place.

flag^abort^transaction

I/O: Output

INT:ref:*

0

Indicates the calling requester program to finish the current transaction normally (END-TRANSACTION)

1

Indicates the calling requester program to abort the current transaction (ABORT-TRANSACTION)

server^class^name

I/O: Output

STRING:ref:*

Identifies the name of the server class to which the data will be forwarded.

server^class^length

I/O: Output

INT:ref:*

Identifies the length (in bytes) of the server class name.

data^message

I/O: Output

STRING.EXT:ref:*

Identifies a pointer to the buffer containing the data returned from the applications servers.

data^length

I/O: Output

INT(32):ref:*

Identifies the length of the data^message buffer.

diagnostic^message

I/O: Output

STRING.EXT:ref:*

Identifies a pointer to the diagnostic message buffer.

diagnostic^length

I/O: Output

INT:ref:*

Identifies the length (in bytes) of the diagnostic message buffer.

pathsend^write^length

I/O: Output

INT:ref:*

Returns the length (in bytes) of the buffer to be sent to the application server.

error^code

I/O: Output

INT:ref:*

Identifies a field always returning a value of -1.

error^subcode

I/O: Output

INT:ref:*

Identifies a field always returning a value of -1.

Example

! Send the data buffer to the server denoted by the server^class^name parameter
! using the SENDSERVER_CLASS_call
error := SERVERCLASS_SEND_( pathmon^name
                           ,pathmon^name^len
                           ,server^class^name
                           ,server^class^name^len
                           ,data^buffer
                           ,write^length
                           ,MAX^REPLY^LEN
                           ,count^read
                           ,timeout
                           ,flags
                           ,^ScSendOpNum );
IF error^code <> FEOK then
            call error^routine;
!Verify SERVER information
CALL DECODE^SERVER^IPC( data^buffer
                       ,reply^code
                       ,flag^change
                       ,flag^abort^transaction
                       ,server^class^name
                       ,server^class^name^len
                       ,data^message
                       ,data^length
                       ,diagnostic^message
                       ,diagnostic^length
                       ,write^length
                       ,error^code
                       ,error^subcode );
! Check for errors
  IF error^code <> -1 then
            call error^routine;

PREPARE^SERVER^IPC Routine—Set Attributes Within AEF Data Structures

The user program must call this procedure each time the requester is ready to prepare the data buffer to be sent to the application servers.

Usage

The syntax of the PREPARE^SERVER^IPC call is:

CALL PREPARE^SERVER^IPC( data^message                    !input
                        ,data^length                     !input
                        ,trancode                        !input
                        ,trancode^len                    !input
                        ,ipc^interface                   !input/output
                        ,write^length                    !output
                        ,error^code                      !output
                        ,error^subcode );                !output

Description

You can use the PREPARE^SERVER^IPC routine to set the appropriate attributes within the AEF data structures. It must be called before sending data to the application servers.

Parameters

data^message

I/O: Input

STRING.EXT:ref:*

Identifies a pointer to the buffer containing the data to be passed to the application.

data^length

I/O: Input

INT(32) value

Identifies a field that contains the length of the data^message buffer.

trancode

I/O: Input

STRING:ref:*

Identifies the transaction.

trancode^len

I/O: Input

INT value

Displays the length (in bytes) of the transaction identifier.

ipc^interface

I/O: Input/Output

STRING.EXT:ref:*

Identifies a buffer interface that will act as a place holder for the data^message buffer.

pathsend^write^length

I/O: Output

INT:ref:*

Returns the length (in bytes) of the buffer to be sent to the application server.

error^code

I/O: Output

INT:ref:*

Returns a value showing the state of the call when it completes.

-1

Indicates no errors.

3

Identifies the length of the data that exceeded the maximum buffer size used by the AEF.

error^subcode

I/O: Output

INT:ref:*

Identifies a field always returning a value of -1.

Example

!Obtain input data.  In this case input is coming from a terminal device
call writeread^terminal( trm^num
                        ,data^message
                        ,data^length
                        ,diag^message
                        ,diag^length );
!Prepare data buffer to be sent to the application servers
CALL PREPARE^SERVER^IPC( data^message
                        ,data^length
                        ,trancode
                        ,trancode^len
                        ,ipc^interface
                        ,write^length
                        ,error^code
                        ,error^subcode );
! Check for errors
  IF error^code <> -1 then
            call error^routine;

Sample Programs

The IT provides the following sample programs to assist you in understanding the use of the IPCO library routines:

• NTCPR1
• NTCPR2

The following sections provide brief descriptions about each program.

NTCPR1

The NTCPR1 sample program is provided as a template to communicate with a CA Gen application using the following logic:

1. Initialize the IPC's information to generate an initial message.
2. Send a message to MSGRT using pathsend.
3. Decode the information returned from MSGRT (basically to retrieve a server class name).
4. Send a message to the server class name. Repeat until there are no changes to another server class.
5. Decode the information from the application (basically data, diagnostic information, or both).
6. Write data or diagnostic information and read your input from the terminal.
7. Prepare a message for the IPC with your input to generate a new message.
8. Repeat Step 2 to Step 7.

The NTCPR1 sample program is built using the following build instructions:

1. Set your current volume to where the IT is located.
2. Issue the following compile command:

   For TNS/R servers

   pTAL / in ntcpr1s, out $l.#ntc1 / ntcpr1o; symbols, nomap, optimize 0, nowarn 4301, fieldalign(platform), srl
   

   For TNS/E servers

   pTAL / in ntcpr1s, out $l.#ntc1 / ntcpr1o; symbols, nomap, optimize 0, nowarn 4301, fieldalign(platform)
   

3. Issue the following link command:

   For TNS/R servers

   NLD / name, out $l.#ntcp / ntcpr1o -o ntcpr1 ipco
   

   For TNS/E servers

   ELD / name, out $l.#ntcp / ntcpr1o -o ntcpr1 ipco
   

To test with the built NTCPR1, perform the following steps:

1. Set your current volume to the location of your CA Gen application.
2. Start your application by issuing the PWCOLD command.
3. Set your current volume to the location of the NTCPR1 program.
4. Start the NTCPR1 program:

   NTCPR1
   

5. Input the following data:
   • Pathmon name
   • Initial trancode
   • Clear screen options
   • Terminal ID
   • Display subtype (nonExtended or extended)
   • Trace flag
   • User ID
   • Printer name

NTCPR2

The NTCPR2 sample program is provided as a template to communicate with a CA Gen application using the following logic:

1. Initialize the IPC's information to generate a initial message.
2. Send a message to MSGRT using pathsend.
3. Decode the information returned from MSGRT (basically to retrieve a server class name).
4. Send a message to the server class name. Repeat until there are no changes to another server class.
5. Decode the information from the application (basically data, diagnostic information, or both).
6. Write data or diagnostic information and read your input from the terminal.
7. Find the trancode in your input.
8. Prepare a message for the IPC with your input to generate a new message.
9. Repeat Step 4 to Step 8.

The NTCPR2 sample program is built using the following build instructions:

1. Set your current volume to the where the IT is located.
2. Issue the following compile command:

   For TNS/R servers

   pTAL / in ntcpr2s, out $l.#ntc1 / ntcpr2o; symbols, nomap, optimize 0, nowarn 4301, fieldalign(platform), srl
   

   For TNS/E servers

   pTAL / in ntcpr2s, out $l.#ntc2 / ntcpr2o; symbols, nomap, optimize 0, nowarn 4301, fieldalign(platform)
   

3. Issue the following link command:

   For TNS/R servers

   NLD / name, out $l.#ntcp / ntcpr2o -o ntcpr2 ipco
   

   For TNS/E servers

   ELD / name, out $l.#ntcp / ntcpr2o -o ntcpr2 ipco
   

To test with the built NTCPR2, perform the following steps:

1. Set your current volume to the location of your CA Gen application.
2. Start your application by issuing the PWCOLD command.
3. Set your current volume to the location of the NTCPR2 program.
4. Start the NTCPR2 program:

   NTCPR2
   

5. Input the following data:
   • Pathmon name
   • Initial trancode
   • Clear screen options
   • Terminal ID
   • Display subtype (nonExtended or extended)
   • Trace flag
   • User ID
   • Printer name