ACTIVATE-USER-EXIT

This statement readies the user exits for the SHOW-ELEMENT or COMPARE-ELEMENT function.

ACTIVATE-USER-EXIT permits LMS to branch to a user routine prior to processing a member record.

Before LMS processes the member record, the following actions are possible:

• update the current member record

• insert records via the user routine

• exclude the current member record from processing

The user routine is informed of start and end of member so as to enable the user to insert records before the first and after the last member record.

For COMPARE-ELEMENT, two user exits are provided: one for the primary member and one for the secondary member. The user exits for SHOW-ELEMENT and COMPARE-ELEMENT can be defined simultaneously.

If several ACTIVATE-USER-EXIT statements with the same user exit are defined, the last one specified applies.

The activated user exits can be deactivated again by means of the DEACTIVATE-USER-EXIT statement.

The ACTIVATE-USER-EXIT statement requires specification of the function for which the user exit is to be activated, and of the entry point of the user program. All other parameters are preset, i.e. the user program is normally dynamically linked from the TASKLIB library.

ACTIVATE-USER-EXIT

FUNCTION = *SHOW-ELEMENT / *COMPARE-ELEMENT(...)
	*COMPARE-ELEMENT(...)
			ELEMENT = *PRIMARY / *SECONDARY
,ENTRY = <name 1..8>
,LIBRARY = *TASKLIB / *OMF / <filename 1..54>
,INTERFACE-VERSION = *V1 / *V2

FUNCTION = *SHOW-ELEMENT / *COMPARE-ELEMENT(...)

Defines the LMS statement for which the user exit is to be activated.

FUNCTION = *SHOW-ELEMENT
User exit for the SHOW-ELEMENT function. Valid for all text member types R, F, H, U and member types derived from them.

FUNCTION = *COMPARE-ELEMENT
User exit for the COMPARE-ELEMENT function. Valid for all text member types R, F, H, U and member types derived from them.

ELEMENT = *PRIMARY / *SECONDARY
If the user exit is activated for the COMPARE-ELEMENT statement, it is also necessary to specify whether the member is a primary member or a secondary member.

ENTRY = <name 1..8>
Name up to 8 characters in length of the entry point of the user routine. The name must not commence with the character string ’LMS’.

LIBRARY = *TASKLIB / *OMF / <filename 1..54>
Source containing the user module.

LIBRARY = *TASKLIB
The desired module is dynamically linked from the TASKLIB (see “Dynamically loading the user program” on "ACTIVATE-USER-EXIT").

LIBRARY = *OMF
The desired module is dynamically linked from *OMF.

LIBRARY = <filename 1..54>
The desired module is dynamically linked from the specified library.

INTERFACE-VERSION = *V1 / *V2
Two interface versions exist. For reasons of compatibility the values BOE, REC and EOE are offered as standard. When specifying V2, the interface is expanded by the values
C’BOS’ (beginning of statement) and C’EOS’ (end of statement). The user program is thus informed of the beginning and end of the statement.

Statement return code

(SC2)        SC1	Maincode	Meaning
0 1 32 64 130	CMD0001 CMD0230 LMS1002 LMS1004 LMS0041	No error Syntax error Internal error Other error System address space exhausted

Required access rights

The user program is linked in dynamically, which means that the access rights depend on the behavior of the BIND macro.

Dynamically loading the user program

The user program is always loaded into user-own class 6 memory. If the specification of a library is omitted under LIBRARY, the user program will first be sought in a private TASKLIB (assigned with /SET-TASKLIB LIBRARY=library), if present, and then in the system TASKLIB ($TASKLIB). If LIBRARY = *OMF or a file is specified but the user program is not found there, the user program is sought in the library assigned with LINK=BLSLIB or in the libraries assigned with LINK= BLSLIBnn (00 ≤ nn ≤ 99), with ascending number “nn”.

User exit interface

• Register conventions

  When the user program is called, LMS will take account of the following register conventions:

  Register 1:	Address of a parameter list
  Register 13:	Address of the save area (18 words)
  Register 14:	Return address
  Register 15:	Address of entry point

• Structure of the parameter list

  The parameter list consists of 5 words:

  DC A(job description)
  DC A(response description)
  DC A(record to be transferred)
  DC A(library name)
  DC A(member designation)
  

  The first two addresses are provided by LMS. This means that the user can only supply the response description to the address that is specified by LMS. The record address can be supplied by both LMS and the user.

  1st word: Job description

  The job description for the user subroutine consists of 3 bytes and can have the following contents:

  C’BOE’ C’REC’ C’EOE’

  Beginning of member (element) Record ready to be processed End of member (element)

  If the expanded interface has been selected, the job description can have the following contents:

  C’BOS’ C’BOE’ C’REC’ C’EOE’ C’EOS’

  Beginning of statement Beginning of member (element) Record ready to be processed End of member (element) End of statement

  2nd word: Response description

  The response description issued by the user subroutine consists of 3 bytes and may have the following contents:

  C’CON’	LMS processes the record whose address is in the parameter list on return from the user program, and then submits the next member record or EOE.
  C’DEL’	LMS bypasses the last submitted member record and branches back to the user subroutine at the next member record or at EOE.
  C’INS’	LMS first processes the record submitted by the user, and then returns to the user subroutine at the member record submitted previously or at EOE. This is repeated until the user responds with DEL or CON. This means that, if LMS submits record i, the records returned with INS are processed before record i.

  The following job responses are possible:

  Job	Response
  BOS	Irrelevant
  BOE	Irrelevant
  REC	CON, DEL, INS
  EOE	CON, INS
  EOS	Irrelevant

  If the response is incorrect, the LMS function is aborted and an error message is issued.

  The diagram below illustrates the communication between LMS and the user subroutine.

  3rd word: Record

  This contains the address of the record that is passed by LMS to the user subroutine. When the user subroutine returns with the response CON or DEL, the same record address may be used. If the user wants to insert records, he must use a record buffer he has defined himself.
  The records exchanged between LMS and the user subroutine start with a 4-byte record length field.
  In order to list P-type members with SHOW-ELEMENT, the 5th byte must be a valid feed control character.

  4th word: Library name

  This word contains the address of the library name of the library currently being processed by LMS. The library name starts with a two-byte record length field.

  5th word: Member designation

  This word contains the address of the member designation of the member currently being processed by LMS. The member designation has the following format: two-byte record length field, followed by

  (type)membername/version[(variantnumber)]/date

Action in LMSAction in user program

Figure 10: Communication between LMS and user programs

For an executable example involving a user exit, see "Branching to a user program while a member is being listed".

Examples

• Minimum specification for the statement ACTIVATE-USER-EXIT.
  The user program “module1” is readied as a user exit for the SHOW-ELEMENT function.

  //activate-user-exit function=*show-element, entry=module1

• The desired user program is contained in the *OMF library.

  //activate-user-exit function=*show-element, entry=module1,library=*omf