Initialization Routine – IRXINIT - IBM-REXX

Use IRXINIT to either initialize a new language processor environment or obtain the address of the environment block for the current non-reentrant environment. The ″current″ environment is the last non-reentrant environment created on this task control block (TCB) or a parent TCB. A non-reentrant environment found on a parent TCB is only considered ″current″ if it is integrated into TSO/E (TSOFL=’1’B).

Tip: To permit FORTRAN programs to call IRXINIT, TSO/E provides an alternate entry point for the IRXINIT routine. The alternate entry point name is IRXINT.

If you use IRXINIT to obtain the address of the current environment block, IRXINIT returns the address in register 0 and also in the sixth parameter.

If you use IRXINIT to initialize a language processor environment, the characteristics for the new environment are based on parameters that you pass on the call and values that are defined for the previous environment. Generally, if you do not pass a specific parameter on the call, IRXINIT uses the value from the previous environment.

IRXINIT always locates a previous environment as follows. On the call to IRXINIT, you can pass the address of an environment block in register 0.IRXINIT then uses this environment as the previous environment if the environment is valid. If register 0 does not contain the address of an environment block,IRXINIT locates the previous environment.If IRXINIT locates a previous environment,IRXINIT uses that environment as the previousenvironment. If IRXINIT cannot locate an environment,IRXINIT uses the load module IRXPARMS as the previous environment.

A previous environment is always identified regardless of the parameters you specify on the call to IRXINIT.

Using IRXINIT, you can initialize a reentrant or a non-reentrant environment, which is determined by the setting of the RENTRANT flag bit. If you use IRXINIT to initialize a reentrant environment and you want to chain the new environment to a previous reentrant environment,you must pass the address of the environment block for the previous reentrant environment in register 0.

If you use IRXINIT to locate a previous environment, you can locate only the current non-reentrant environment. IRXINIT does not locate a reentrant environment.

You can use IRXINIT CHEKENVB to verify that an address is a valid ENVBLOCK:

  • under the current task
  • under a parent task
  • is not under the current task or under a parent task.

Entry Specifications

For the IRXINIT initialization routine, the contents of the registers on entry are:

Register 0 Address of an environment block (optional for FINDENVB and INITENVB, required for CHEKENVB)

Register 1 Address of the parameter list passed by the caller

Registers 2-12 Unpredictable

Register 13 Address of a register save area

Register 14 Return address

Register 15 Entry point address

Parameters

You can pass the address of an environment block in register 0. In register 1, you pass the address of a parameter list, which consists of a list of addresses. Each address in the parameter list points to a parameter.

The first seven parameters are required. Parameter 8 and parameter 9 are optional. The high-order bit of the last address in the parameter list must be set to 1 to indicate the end of the parameter list. If IRXINIT does not find the high-order bit set on in either the address for parameter 7 or in the addresses for parameters 8 or 9, which are optional parameters, IRXINIT does not initialize the environment and returns with a return code of 20 and a reason code of 27.

The describes the parameters for IRXINIT.

Parameters for IRXINIT

Parameters for IRXINIT

Parameters for IRXINITSpecifying How REXX Obtains Storage in the Environment

On the call to IRXINIT, parameter 8 is an optional parameter. You can use parameter 8 to specify how REXX obtains storage in the language processor environment for the processing of REXX execs.

If you specify 0 for parameter 8,during the initialization of the environment, the system reserves a default amount of storage for the storage workarea. If you have provided your own storage management replaceable routine, the system calls your routine to obtain this storage workarea.Otherwise, the system obtains storage using GETMAIN. When the environment that IRXINIT is initializing is terminated, the system automatically frees the storage. The system frees the storage by either calling your storage management replaceable routine or using FREEMAIN, depending on how the storage was obtained.

You can also pass a storage workarea to IRXINIT. For parameter 8, specify an address that points to an extended parameter list. The extended parameter list is an address/length pair that contains the address (a fullword) of the storage workarea and the length (a fullword) of the storage area, in bytes. The address/length pair must be followed by X'FFFFFFFFFFFFFFFF' to indicate the end of the extended parameter list. Figure below shows the extended parameter list.

Extended Parameter List – Parameter 8

Extended Parameter List – Parameter 8

The storage workarea you pass to IRXINIT is then available for REXX processing in the environment that you are initializing. The storage workarea must remain available to the environment until the environment is terminated. After you terminate the language processor environment, you must also free the storage workarea. The system does not free the storage you pass to IRXINIT when you terminate the environment.

You can also specify that a reserved storage workarea should not be initialized for the environment. The system then obtains and frees storage whenever storage is required. To specify that a storage workarea should not be initialized, for parameter 8, specify the address of the extended parameter list as described above. In the extended parameter list, specify 0 for the address of the storage workarea and 0 for the length of the storage workarea. Again, the address/length pair must be followed by X'FFFFFFFFFFFFFFFF' to indicate the end of the extended parameter list. Specifying that REXX should run without a reserved storage workarea is not suggested because of possible performance degradation. However, this option may be useful if available storage is low and you want to initialize a language processor environment with a minimal amount of storage at initialization time.

In the extended parameter list, you can also specify 0 for the address of the storage workarea and -1 for the length of the workarea. This is considered a null entry and IRXINIT ignores the extended parameter list entry. This is equivalent to specifying an address of 0 for parameter 8, and the system reserves a default amount of workarea storage.

In general, 3 pages (12K) of storage is needed for the storage workarea for normal exec processing, for each level of exec nesting. If there is insufficient storage available in the storage workarea, REXX calls the storage management routine to obtain additional storage if you provided a storage management replaceable routine. Otherwise, the system uses GETMAIN and FREEMAIN to obtain and free storage.

How IRXINIT Determines What Values to Use for the Environment

IRXINIT first determines the values to use to initialize the environment. After all of the values are determined, IRXINIT initializes the new environment using the values.

On the call to IRXINIT, you can pass parameters that define the environment in two ways. You can specify the name of a parameters module (a load module) that contains the values IRXINIT uses to initialize the environment. In addition to the parameters module, you can also pass an address of an area in storage that contains the parameters. This area in storage is called an in-storage parameter list and the parameters it contains are equivalent to the parameters in the parameters module.

The two methods of passing parameter values give you flexibility when calling IRXINIT. You can store the values on disk or build the parameter structure in storage dynamically. The format of the parameters module and the in-storage parameter list is the same. You can pass a value for the same parameter in both the parameters module and the in-storage parameter list.

When IRXINIT computes what values to use to initialize the environment, IRXINIT takes values from four sources using the following hierarchical search order:

  1. The in-storage list of parameters that you pass on the call. If you pass an in-storage parameter list and the value in the list is not null, IRXINIT uses this value. Otherwise, IRXINIT continues.
  2. The parameters module, the name of which you pass on the call. If you pass a parameters module and the value in the module is not null, IRXINIT uses this value. Otherwise, IRXINIT continues.
  3. The previous environment.IRXINIT copies the value from the previous environment.
  4. The IRXPARMS parameters module if a previous environment does not exist.

If a parameter has a null value, IRXINIT continues to search until it finds a non-null value. The following types of parameters are defined to be null:

  • A character string is null if it either contains only blanks or has a length of zero
  • An address is null if its value is 0 (or X'80000000', when specified for the user field parameter in the IRXINIT parameter list)
  • A binary number is null if it has the value X'80000000'
  • A given bit is null if its corresponding mask is 0.

On the call to IRXINIT, if the address of the in-storage parameter list is 0, all values in the list are defined as null. Similarly, if the name of the parameters module is blank, all values in the parameters module are defined as null.

You need not specify a value for every parameter in the parameters module or the in-storage parameter list. If you do not specify a value, IRXINIT uses the value defined for the previous environment. You need only specify the parameters whose values you want to be different from the previous environment.

Parameters Module and In-Storage Parameter List

The parameters module is a load module that contains the values you want IRXINIT to use to initialize a new language processor environment. TSO/E provides three default parameters modules (IRXPARMS, IRXTSPRM, and IRXISPRM) for initializing environments in non-TSO/E, TSO/E, and ISPF.

On the call to the IRXINIT, you can optionally pass the name of a parameters module that you have created.The parameters module contains the values you want IRXINIT to use to initialize the new language processor environment. On the call, you can also optionally pass the address of an in-storage parameter list. The format of the parameters module and the in-storage parameter list is identical.

This shows the format of a parameters module and in-storage list. The format of the parameters module is identical to the default modules TSO/E provides

Parameters Module and In-Storage Parameter List

Parameters Module and In-Storage Parameter List

Specifying Values for the New Environment

If you use IRXINIT to initialize a new language processor environment, the parameters you can specify on the call depend on:

  • Whether the environment is being initialized in a non-TSO/E address space or in the TSO/E address space
  • If the environment is being initialized in the TSO/E address space, whether the environment is to be integrated into TSO/E (TSOFL flag setting)

You can use many parameters only if the environment is initialized in a non-TSO/E address space or if the environment is initialized in TSO/E, but is not integrated into TSO/E (the TSOFL flag is off). Other parameters are intended only for use in the TSO/E address space where the environment is integrated into TSO/E (the TSOFL flag is on). The following information highlights different parameters.

When you call IRXINIT, you cannot specify the ID and VERSION.If you pass values for the ID or VERSION parameters, IRXINIT ignores the value and uses the default.

At offset +36 in the parameters module, the field is a fullword of bits that IRXINIT uses as flags. The flags define certain characteristics for the new language processor environment and how the environment and execs running in the environment operate. In addition to the flags field, the parameter following the flags is a mask field that works together with the flags. The mask field is a string that has the same length as the flags field. Each bit position in the mask field corresponds to a bit in the same position in the flags field. IRXINIT uses the mask field to determine whether it should use or ignore the corresponding flag bit.

The description of the mask field describes the bit settings for the mask field in detail. The summarizes each flag.

For a given bit position, if the value in the mask field is:

  • 0 – IRXINIT ignores the corresponding bit in the flags field (that is, IRXINIT considers the bit to be null)
  • 1 – IRXINIT uses the corresponding bit in the flags field

When you call IRXINIT, the flag settings that IRXINIT uses depend on the:

  • Bit settings in the flag and mask fields you pass in the in-storage parameter list
  • Bit settings in the flag and mask fields you pass in the parameters module
  • Flags defined for the previous environment
  • Flags defined in IRXPARMS if a previous environment does not exist.

IRXINIT uses the following order to determine what value to use for each flag bit:

  • IRXINIT first checks the mask setting in the in-storage parameter list. If the mask is 1, IRXINIT uses the flag value from the in-storage parameter list.
  • If the mask in the in-storage parameter list is 0, IRXINIT then checks the mask setting in the parameters module. If the mask in the parameters module is 1, IRXINIT uses the flag value from the parameters module.
  • If the mask in the parameters module is 0,IRXINIT uses the flag value defined for the previous environment.
  • If a previous environment does not exist,IRXINIT uses the flag setting from
    IRXPARMS.

If you call IRXINIT to initialize an environment that is not integrated into TSO/E (the TSOFL flag is off), you can specify a subpool number (SUBPOOL field) from 0 – 127. IRXINIT does not check the number you provide. If the number is not 0 – 127, IRXINIT does not fail. However, when storage is used in the environment, an error occurs.

If you call IRXINIT to initialize an environment in the TSO/E address space and the environment is integrated into TSO/E, you must provide a subpool number of 78 (decimal). If the number is not 78, IRXINIT returns with a reason code of 7 in parameter 7.

The end of the parameter block must be indicated by X'FFFFFFFFFFFFFFFF'.

Return Specifications

For the IRXINIT initialization routine, the contents of the registers on return are:

Register 0
Contains the address of the new environment block if IRXINIT initialized a new
environment, or the address of the environment block for the current non-reentrant environment that IRXINIT located.

If you called IRXINIT to initialize a new environment and IRXINIT could not initialize the environment, register 0 contains the same value as on entry. If you called IRXINIT to find an environment and IRXINIT could not locate the environment, register 0 contains a 0.If IRXINIT returns with return code 100 or 104, register 0 contains the abend and reason code.

Register 1 Address of the parameter list.

IRXINIT uses three parameters for output only.

Registers 2-14 Same as on entry

Register 15 Return code

Output Parameters

The parameter list for IRXINIT contains three parameters that IRXINIT uses for output only (parameters 6, 7, and 9). Parameter 6 contains the address of the environment block. If you called IRXINIT to locate an environment, parameter 6 contains the address of the environment block for the current non-reentrant environment. If you called IRXINIT to initialize an environment, parameter 6 contains the address of the environment block for the new environment. Parameter 6 lets high-level programming languages obtain the address of the environment block to examine information in the environment block.

Parameter 9 is an optional parameter you can use to obtain the return code. If you specify parameter 9, IRXINIT returns the return code in parameter 9 and also in register 15.

Parameter 7 contains a reason code for IRXINIT processing. The reason code indicates whether IRXINIT completed successfully. If IRXINIT processing was not successful, the reason code indicates the error. The describes the reason codes IRXINIT returns. Note that these reason codes are not the same as the reason codes that are returned because of a system or user abend. A system or user abend results in a return code of 100 or 104 and an abend code and abend reason code in register 0.

Return Codes

IRXINIT returns different return codes for finding an environment and for initializing an environment.IRXINIT returns the return code in register 15. If you specify the return code parameter (parameter 9), IRXINIT also returns the return code in the parameter. This shows the return codes if you call IRXINIT to find an environment.

IRXINIT Return Codes for Finding an Environment

IRXINIT Return Codes for Finding an Environment

This shows the return codes if you call IRXINIT to check an environment.

IRXINIT Return Codes for Checking an Environment

IRXINIT Return Codes for Checking an Environment

This shows the return codes if you call IRXINIT to initialize an environment.

IRXINIT Return Codes for Initializing an Environment

IRXINIT Return Codes for Initializing an Environment

All rights reserved © 2020 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-REXX Topics