Once you have written an API program to run under one release of CICSPlex® SM,
you can continue to access the data provided by that release, or you can access
the data available from a later release of the product. In general, if you
plan to access more than one release of the CICSPlex SM API, keep the following
in mind:
- Run-time environment
- The run-time version of a CICSPlex SM API program is equal to the level
of the CMAS to which it connects:
- For a program written to run as a CICS® application, the run-time version is
that of the CMAS to which the MAS is connected.
- For a program written to run as a batch job or under NetView® or TSO, the
version is determined by the version of the CICSPlex SM run-time module (EYU9AB00),
which is distributed in the version’s SEYUAUTH library.
The run-time version of a program must be greater than or equal to:
- The version of the stub routine module (EYU9AxSI) with which the program
was link edited.
- For CICS programs, the stub module is called EYU9AMSI and is distributed
in the version’s SEYULOAD library.
- For batch, TSO, or NetView programs, the module is called EYU9ABSI and is
distributed in the version’s SEYUAUTH library.
In addition, the version of the stub module for any separately link
edited and called programs must be the same as the version used to link edit
the program that issued the CONNECT command.
- The value specified on the VERSION option of the CONNECT command.
Note:
For programs written in REXX, the run-time version must
be greater than or equal to the version of the function package (EYU9AR00),
which is distributed in the version’s SEYUAUTH library.
- VERSION option
- The VERSION option on the CONNECT command controls which release of CICSPlex SM resource tables
are available to your program (resource tables are the external representation of CICSPlex SM data).
- An API program cannot access data from a release of CICSPlex SM earlier than Release 2 (the
release in which the API was introduced). The VERSION value must be set
to 0120 or greater.
- An API program cannot access data from a release of CICSPlex SM later than
the run-time module that you specify. The VERSION value must be less than
or equal to the release of the run-time module.
- An API program can access data from a later release of CICSPlex SM than that
which the program was originally written for, provided:
- You compile your program using the appropriate copy books for the version
specified.
- Your program is compatible with the copy books for the version specified.
- CONTEXT option
- The CONTEXT option that is supported by various API commands determines
which CICS systems your program receives data from. The CONTEXT value can be set
to any CMAS or CICSplex running any currently supported release of CICSPlex SM.
Note, however, that the release level of the CMAS or CICSplex must be the same
as the release of the run-time module.
- CURRENT option
- When specifying the CURRENT option, the record pointer does not move
(that is, a subsequent FETCH retrieves the same record). Previously, the
record pointer moved to the next record. For further information, see Positioning the record pointer in a result set.
If you have REXX application programs you should be aware of how CICSPlex SM behaves
in the case where you apply a PTF to some members of a CICSplex but not others,
you modify a REXX API program to put a value in a new table field introduced
by the PTF and the REXX program then connects to a CMAS which has not had
the PTF applied, and which therefore has no definition for the new field.
In this case:
- The CMAS does not transmit the value of the new field to the maintenance
point CMAS.
- The maintenance point CMAS (which is at the highest level) transforms
the record area to give a default value to the new field. The new value may
be different from that originally specified by the REXX program.
- The maintenance point CMAS then broadcasts the record back to the originating
CMAS, but transforms the record back to remove the new field. At this point,
the maintenance point repository will not contain the intended value, (it
will contain the default value) and when it has broadcast the record back
to the originating CMAS, this repository will have had the intended value
removed.
- If the same REXX program issues a TPARSE of the record, the value of the
field is still the same as it was at the time it was created, and is not changed
by the TPARSE. This might cause the program to indicate, wrongly, that the
field contains the intended value, whereas, in the maintenance point repository,
the field has the default value, and in the back-level CMAS repository, the
field does not exist.
- If a REXX API program subsequently connects to the back-level CMAS and
issues a TPARSE of the record, the new field will not be populated by the
TPARSE. In this case the field will have the normal REXX default value - the
field value will be the same as the field name.
If the set of circumstances described above applies to you, and might
cause you a problem, your REXX program should contain code to issue a QUERY
to obtain and verify the record length.
In order to migrate your application programs to the new release so that
they can benefit from the full function available there, see Accessing resource tables from a new release.
If you need to continue to run application programs in an earlier release CICSPlex SM environment
whilst being able to manage this environment using the services provided in
the new release, you must first read the sections on CICSPlex SM migration in the CICS Transaction Server for z/OS® Migration from CICS TS Version 2.3.
You can access the most up-to-date CICSPlex SM resource tables by running an existing
program under a new release of the API.
Note:
To take full advantage of a new CICSPlex SM function (such as Business Application Services),
however, you would have to modify an existing program or create a new one.
To run an existing API program under a new release of CICSPlex SM:
- Make sure the following are available to your program:
- The run-time module for the new release (EYU9AB00 from the new release’s
SEYUAUTH library)
- A CMAS that is running the new release
- Change the VERSION value on the CONNECT command to reflect the new release
of CICSPlex SM (for example, 0310 for CICS Transaction Server for z/OS, Version 3 Release 1) and relink-edit the program using the
stub module supplied in the new release.
- Review the possible effects of any changes to the CICSPlex SM resource tables.
Attributes may be added to a resource table in a new release, which could affect
your program's references to that table. And with the addition or modification
of attributes, the length of a given resource table may change from one release
to another. The resource table copy books that are distributed with the new release
are a good source of information about such changes.
Note:
If
there is no requirement to take advantage of the new function in the release
it is possible to continue to run an existing API program unaltered, provided
the VERSION value on the CONNECT command reflects the link-edit level used.
If your program receives RESPONSE and REASON values
of INVALIDPARM LENGTH when you run it under a new release of CICSPlex SM, the table
length may have increased and your data buffer may not be long enough to accommodate
the new resource table records.
- If you are using customized views of resource tables, you are advised to check
that the names of any new resource tables do not duplicate the names of your customized
views, as this could affect your processing. For further details, see Building a customized resource table record.
For a complete list of new and changed resource tables in a given release,
refer to CICSPlex System Manager Resource Tables Reference.
To continue accessing the resource tables supplied with a previous release of CICSPlex SM:
- Specify the release of CICSPlex SM data that you want to access on the VERSION
option of the CONNECT command.
- Use the run-time module (EYU9AB00) supplied with the release you want
to access or a subsequent release that supports it.
- Use a version of the stub module (EYU9AxSI) that is less than or equal
to the run-time module.
Table 4 illustrates some valid combinations of the VERSION
option, stub module and run-time module for accessing data from different
releases of CICSPlex SM.
Table 4. Valid ways to access data from different releases
VERSION
value |
Stub module
(EYU9AxSI) |
Run-time module
(EYU9AB00) |
CMASs available |
CMAS used |
Data available |
0220 |
V2R2 |
V2R2 |
V1R2
V1R3
V1R4
V2R1
V2R2 |
V2R2 |
V2R2 |
0120 |
V1R2 |
V1R2 |
V1R2 |
V1R2 |
V1R2 |
0120 |
V1R2 |
V1R3 |
V1R3 |
V1R3 |
V1R2 |
0120 |
V1R3 |
V1R3 |
V1R2
V1R3 |
V1R3 |
V1R2 |
0120 |
V1R4 |
V1R4 |
V1R2
V1R3
V1R4 |
V1R2 |
V1R2 |
0130 |
V1R3 |
V1R3 |
V1R2
V1R3 |
V1R3 |
V1R3 |
0130 |
V1R3 |
V1R4 |
V1R2
V1R3
V1R4 |
V1R4 |
V1R3 |
0130 |
V1R4 |
V1R4 |
V1R2
V1R3
V1R4 |
V1R4 |
V1R3 |
0140 |
V1R4 |
V1R4 |
V1R2
V1R3
V1R4 |
V1R4 |
V1R4 |
0210 |
V2R1 |
V2R1 |
V1R2
V1R3
V1R4 V2R1 |
V2R1 |
V2R1 |
Table 5 shows some invalid combinations of the VERSION option,
run-time module, and stub module and describes why they produce an error.
Table 5. Common errors in accessing different releases
VERSION
value |
Stub module
(EYU9AxSI) |
Run-time module
(EYU9AB00) |
CMASs available |
Error description |
0140 |
V2R1 |
V1R4 |
V1R4
V2R1 |
Stub module release level is greater than run-time module. |
0210 |
V2R1 |
V1R4 |
V1R4
V2R1 |
Stub module release level is greater than run-time module. |
0210 |
V1R4 |
V1R4 |
V1R4 |
VERSION value is greater than run-time module. |
0210 |
V2R1 |
V2R1 |
V1R4 |
No CMAS available at the required run-time level. |
Note:
For programs written in REXX, the compatibility issues are
similar. The Release 2 function package (which contains the necessary stub module)
can run successfully with either the Release 2 or Release 3 run-time module. The Release 3 function
package, however, cannot run with the Release 2 run-time module; the Release 3 module
is required.
[[ Contents Previous Page | Next Page Index ]]