INMC Security Exit Support › Writing a Primary Exit

Writing a Primary Exit

The primary exit is called by your product region with Register 1 containing the address of a parameter list which is always ten consecutive full words in length.

Depending upon the reason for the call, some of these words might be set to binary zeroes.

The first word of the parameter list is always the address of a full word that contains a function code identifying the type of call being made.

The other parameters passed depend upon the value of this function code and the exit must therefore determine the function code first in order to decide which parameters to expect.

The parameter list passed to the exit is also used as a parameter list returned from the exit, allowing the exit to indicate the processing required and to pass the appropriate information to your product region.

Note: On a call to the exit, addresses of various fields are included in the parameter list. Only these fields can be used to return information from the exit; the exit cannot pass parameters back to your product region in any other locations.

Specifying Initialization Processing

Initialization processing notifies the primary exit of two things:

• The INMC link to the specified remote system has been activated
• Whether the remote system is configured with a secondary exit to which the primary exit can send messages

To provide this functionality in your exit, you must code the initialization call to correspond with the parameter list in the following section.

You must take into consideration any special processing you want to perform, such as, password exchange between the connecting systems.

Initialization Call Parameter List

On entry to the Primary exit, Register 1 points to a list of ten full words, as shown in this diagram.

• Word 1

  Points to a full word containing function code X'00000000'. Other words in the parameter list point to additional parameters.

• Word 2

  Is the address of the 1 to 12 character link name of the remote system with which a link has been established.

• Word 3

  Is the address of a 1-byte field that specifies the status of the secondary exit in the remote system. Values of this field and the meanings are as follows:

  Field Value	Definition
  X'00'	A secondary exit is available for communications.
  X'04'	The remote system does not have a secondary exit defined. No SYSPARMS INMCEX02 command has been issued in the remote system.
  X'08'	The remote system has a secondary exit defined but the load module (or phase) was not loaded successfully.

• Word 4

  Is the address of a full word, value F'0'. The primary exit can place in this field the length of a message that is to be sent to the secondary exit in the remote system. The maximum length is 256 bytes (decimal). If a longer length is specified it is truncated to 256. If a negative length is specified it is forced to 256.

• Word 5

  Is the address of an area in which the primary exit can place the text of a message that is to be sent to the secondary exit in the remote system. The message is assumed to be left aligned in this message area. The maximum message text length is 256 (decimal) bytes. The data in the message can be binary or character and is transparent to your region. The meaning and format of the message sent to the secondary exit is determined by the installation.

• Words 6 to 10

  Are set to zero.

Return Codes from Initialization Call

On return from the initialization call, the primary exit signals what it wants done next. The choices that are available are:

• Send a message to the secondary exit in the remote system.
• Terminate exit processing.

The exit indicates which option is required by using the same ten full words of the parameter list with which it was called, to pass back its own instructions to your region. When the exit returns therefore, the ten full word parameter list must be formatted as follows:

• Word 1

  Is the address of a function code specifying the action that the exit wishes your region to take. Values of this function code and their meanings are as follows:

  Function Code	Definition
  F'0'	A message is to be sent to the secondary exit in the remote system.
  F'4'	Exit processing is to terminate.

• Word 2

  Is unchanged and not used.

• Word 3

  Is the address of a 1-byte field. This is the same address as was passed to the exit in word 3 of the parameter list. The value of this 1-byte field depends upon the function code returned by the exit in word 1. Valid values and their meanings are:

  Function Code			Meaning
  F'0'		Function code not used.
  F'4'	X'00'	Allow normal link activation
  	X'04'	Allow link to remain open but allow no traffic to flow
  	X'08'	Close the link

• Word 4

  Is not used for function code F'4'. For function code F'0' this word holds the address of a full word in which the primary exit can place the binary length of a message that is to be sent to the secondary exit in the remote system. The maximum length is 256 bytes (decimal). If a longer length is specified it is truncated to 256. If a negative length is specified it is forced to 256. This is the same address as passed to the exit in word 4 of the parameter list.

• Word 5

  Is not used for function code F'4'. For function code F'0' this word holds the address of an area in which the primary exit can place the text of a message that is to be sent to the secondary exit in the remote system. The message is assumed to be left aligned in this message area. The maximum message text length is 256 (decimal) bytes. The data in the message can be binary or character and is transparent to your region. The meaning and format of the message sent to the secondary exit is determined by the installation. This is the same address as passed to the exit in word 5 of the parameter list.

• Words 6 to 10

  Are set to zero.

Specifying Message Delivery Processing

When the primary exit sends a message to the secondary exit in a remote system, the secondary exit always responds with a reply. That reply can be a null message of zero length. The reply message is presented to the primary exit for processing by using a Deliver Call.

The primary exit performs whatever processing is required and then returns to your region with the ten full word parameter list set to indicate the processing required next.

On return, the exit can request one of two options:

• Exit processing is to terminate.
• A message is to be sent to the secondary exit.

Delivery Call Parameter List

On entry to the primary exit, Register 1 points to a list of ten full words, as shown in this diagram.

• Word 1

  Points to a full word containing function code X'00000004'.

• Word 2

  Is the address of the link name of the remote system with which a link has been established.

• Word 3

  Is the address of a full word in which the primary exit can return a code indicating whether the link is to be opened for normal INMC traffic.

• Word 4

  Is the address of a full word, value F'0'. The primary exit can place in this field the length of a message that is to be sent to the secondary exit in the remote system. The maximum length is 256 bytes (decimal). If a longer length is specified it is truncated to 256. If a negative length is specified it is forced to 256.

• Word 5

  Is the address of an area in which the primary exit can place the text of a message that is to be sent to the secondary exit in the remote system. The message is assumed to be left aligned in this message area. The maximum message text length is 256 bytes (decimal). The data in the message can be binary or character and is transparent to your region. The meaning and format of the message sent to the secondary exit is determined by the installation.

• Word 6

  Is the address of a full word containing the length of a message sent from the secondary exit in the remote system. The maximum length is 256 bytes (decimal), minimum is zero (which would be a null message).

• Word 7

  Is the address of the message sent from the secondary exit.

• Words 8 to 10

  Are set to zero.

Return Codes from Delivery Call

When the primary exit completes its processing of the message returned from the secondary exit it formats the ten word parameter list to indicate the processing required next and then returns to your region.

The parameter list must be set exactly.

Specifying Termination of Link Notification Processing

If a link to a remote system is lost before a reply is received from the secondary exit, your region indicates this to the primary exit via a notify call. This call tells the primary exit that no further communications can be received from the secondary exit and that the INMC link to the remote system has been lost.

A notify call is also made in response to the primary exit attempting to communicate with a secondary exit when the remote system is not configured with a secondary exit or the secondary exit failed to initialize.

When the exit has been notified of a lost link, it should then perform whatever termination processing it needs to do then return to your region, indicating that exit processing is to terminate. Any other action results in repetitive notify calls until the exit signals that exit processing is to end.

Notify Call Parameter List

On entry to the primary exit, Register 1 points to a list of ten full words, as shown in this diagram.

• Word 1

  Points to a full word containing function code X'00000008'.

• Word 2

  Is the address of the link name of the remote system with which contact has been lost.

• Word 3

  Is the address of 1-byte field containing a notify code. Valid values are as follows:

  Field Value	Definition
  X'04'	The remote system does not have a secondary exit defined. No SYSPARMS INMCEX02 command has been issued in the remote system.
  X'08'	The remote system has a secondary exit defined but the load module (or phase) was not loaded successfully.
  X'0C'	The link has been lost.

• Words 4 to 10

  Are set to zero.

Return Codes from Notify Call

When the primary exit completes its processing of the notify call it should format the ten word parameter list as follows:

• Word 1

  Is the address of a function code specifying the action that the exit requires your region to take. The values of this function code must be F'4' (Exit processing is to terminate).

The remaining nine full words should be returned unchanged.