In this section: |
On z/OS, you can incorporate an additional routine called MSODDX into a user-written subroutine that needs to access ddnames allocated to a WebFOCUS Reporting Server, a DataMigrator Server, or an Full-function Server. MSODDX provides ddname translation services that enable external programs to access files under the ddname used by the Server.
Why are DDNAMEs Translated?
Users often want to allocate files according to their individual needs, therefore, different allocations for FOCEXEC, MASTER, etc. are likely in each Server task. To keep users' allocations separate, a scheme called ddname translation is used to create unique ddnames for every file belonging to each user. When a user allocates a file, the Server internally generates a unique name to perform the allocation and saves the relationship between the ddname the user sees and the ddname the Server uses for the actual allocation.
For example, the Server's FINDMEM subroutine uses the MSODDX routine as follows. When FINDMEM is passed a ddname, a member name, and a return code field, the subroutine opens the specified ddname to determine if a member with the specified name exists in the file. FINDMEM calls MSODDX to determine the correct ddname to open.
Since the allocation performed within the Server's user session is not done under the same ddname originally specified by the user, when a user-written subroutine needs to access a file the program must determine what the translated ddname is in order to use the actual name when opening the file. This is accomplished by calling the MSODDX routine to perform the translation for you.
Note that only files allocated locally by individual Server users participate in the ddname translation scheme. Those present in the Server start-up JCL (IRUNJCL) are referred to as global ddnames since they are available to all of the server's tasks. Global ddnames are not translated and, therefore, do not require the MSODDX routine.
MSODDX must be called in AMODE31 from an assembly-language program or any high-level language that is LE compliant and supports dynamic specification of the ddname to be opened. Some languages that do this are PL/I and C. Languages that require the ddname to be hard-coded at compilation time are not suitable (except for COBOL, where Information Builders provides MSODDX2 ASSEMBLER to zap the obtained ddname into Cobol FD). For further information, consult the documentation for your compiler.
If you are migrating from a traditional MVS Server (SSCTL), you must re-link your user-written subroutine to the current Server's MSODDX. In addition, if you were previously calling MSODDX in AMODE24 you must now use AMODE31.
MSODDX is typically used to code a user-written subroutine that is callable under the Server and will open and process a file for you. For such a routine, you must call MSODDX once for each file that you open, immediately before issuing the OPEN command.
Using a CALLTYPE of 1 (as described in MSODDX Parameter List), you pass the generic ddname—that is, the ddname that the user specified when the file was allocated. The correct ddname is returned to you. You can either place this into the DCB (using ASSEMBLER), or into a variable (for a high-level language) or for COBOL (using MSODDX2 ASSEMBLER to zap the obtained ddname into a COBOL FD). For details, see ASMDDX - Sample Assembler Exit for MSODDX or COBDDX - Sample COBOL Exit for MSODDX.
You can then issue the OPEN command, and the remainder of your application will proceed normally.
Note that it is not necessary to set CALLTYPE=0 in your application to verify that you are running under the Server because if you call MSODDX when not running under the server, MSODDX merely returns the same ddname you have passed it.
Reference: |
MSODDX uses the standard OS-calling conventions. Register 1 must point to a list of full word addresses, which point to the parameters described below; Register 13 must point to a 72-byte register save area; Register 15 contains the entry point address of MSODDX; and Register 14 contains the return address to your program. (This is all done for you in a high-level language call.)
Note: For assembler-language callers, the return code is provided as one of the parameters and is not given in Register 15 (R15 is returned unchanged).
The following chart describes MSODDX parameters and values. The parameters are labeled to indicate whether a value is expected on input (I) to MSODDX, or will contain a value upon return from MSODDX (O).
Input/Output |
Field |
Contents |
---|---|---|
(I) |
CALLTYPE |
Is the function to be performed. CALLTYPE is a full word (4-byte integer) containing one of the following values:
|
(I/O) |
GENDD |
The generic (untranslated) ddname. GENDD is an eight-byte character field. Its usage is described under the listed CALLTYPE, varying based on the CALLTYPE value. |
(I/O) |
TRANDD |
The actual (translated) ddname. TRANDD is an eight-byte character field. Its usage is described under the listed CALLTYPE, varying based on the CALLTYPE value. |
(I) |
WORKAREA |
It is a 300-byte area used by MSODDX for its work area. You must initialize this area to low values (hex zeroes) prior to the first call you make to MSODDX, and should not alter its contents from then on. |
(O) |
RETCODE |
The return code from MSODDX. RETCODE is a full word (4-byte integer) providing an indication of the results of the call made to MSODDX. The only values ever returned will be zero and four; their meanings are described under the CALLTYPE, varying based on the CALLTYPE performed. |
How to: |
A sample user exit to invoke MSODDX written in Assembler is provided in the Server's qualif.HOME.DATA(ASMDDX) library.
The same library contains the following:
You must edit GENASDDX to compile and link the MSODDX routine into your application.
Edit the sample GENASDDX as follows:
This sets the Assembler source library. (For our sample, this corresponds to qualif.HOME.DATA.)
This sets the Assembler source name. (For our sample, ASMDDX.)
This sets the Object library where MSODDXC resides (qualif.HOME.DATA).
This sets the Output load library.
This sets the Output program name.
This sets the Object data set block size.
This sets the Prelinker message module.
This sets the LE library prefix.
For the sample ASMDDX, <AsmEP> is ASMDDX.
Edit and run the following procedure:
SET EXORDER=PGM/FEX DYNAM ALLOC FILE CAR EX ASMDDX
The ASMDDX load library must be concatenated to the Server's STEPLIB (in IRUNJCL). Sample ASMDDX output goes to server's JESMSGLG output.
Sample output
12.43.31 JOB26648 +DD CAR allocated as SYS00018
In this example, SYS00018 is the translated ddname for CAR in this server's user session.
How to: |
A sample user exit, written in COBOL, is provided to invoke MSODDX in the Server's qualif.HOME.DATA(COBDDX) library.
The same library contains the following:
You must edit GENCPDDX to compile and link the MSODDX routine into your application.
Edit GENCPDDX as follows:
This sets a COBOL source library. For our sample, this corresponds to qualif.HOME.DATA.
This sets the COBOL source name.
This sets the Assembler source library where MSODDX2 resides (qualif.HOME.DATA).
This sets the Output load library.
This sets the Output program name.
This sets the COBOL compiler library prefix.
This sets the Object data set block size.
This sets the Prelinker message module.
This sets the LE library prefix.
Edit and run the following procedure:
SET EXORDER=PGM/FEX -* Alloc local ddname TESTDD and Global ddname CAR. DYNAM ALLOC FI TESTDD -RUN -WRITE TESTDD Line written to TESTDD before invoking COBDDX -CLOSE TESTDD DYNAM ALLOC FI CAR NOALIAS EX COBDDX
COBDDX load library must be concatenated to the Server's STEPLIB (in IRUNJCL). Sample COBDDX output goes to the server's SYSOUT ddname.
Sample output
TESTING CALL TYPE 0 (WHETHER OR NOT UNDER MSO) WE ARE RUNNING UNDER MSO (EDA). RETURN CODE ==> 00000000
TESTING CALL TYPE 1 - STANDARD TRANSLATION CALL FOR A GLOBAL DDNAME - EXPECT SAME DD AS OUTPUT GENERIC DDNAME ==> CAR TRANSLATED DDNAME ==> CAR RETURN CODE ==> 00000000
TESTING CALL TYPE 1 - STANDARD TRANSLATION CALL FOR A USER DDNAME - EXPECT TRANSLATION GENERIC DDNAME ==> TESTDD TRANSLATED DDNAME ==> SYS00003 RETURN CODE ==> 00000000
TESTING CALL TYPE 2 - UNTRANSLATION CALL EXPECT UNTRANSLATION OF DDS USED PREVIOUSLY GENERIC DDNAME ==> TESTDD TRANSLATED DDNAME ==> SYS00003 RETURN CODE ==> 00000000
TESTING MSODDX2. ZAPPING DDNAME TO COBOL FD
EXPECT A LINE TO BE READ FROM TESTDD FILE
TRANSLATED DDNAME ==> SYS00003
LINE READ FROM TRANDD ==> Line written to TESTDD before invoking COBDDX
TESTING CALL TYPE 1 - STANDARD TRANSLATION CALL FOR UNEXISTING DDNAME - EXPECT RETCODE 4 GENERIC DDNAME ==> XXXXXXXX TRANSLATED DDNAME ==> XXXXXXXX RETURN CODE ==> 00000004
TESTING CALL TYPE 2 - UNTRANSLATION CALL FOR GLOBAL DDNAME - EXPECT SAME DD IN GENDD GENERIC DDNAME ==> CAR TRANSLATED DDNAME ==> CAR RETURN CODE ==> 00000004
TESTING CALL TYPE 2 - UNTRANSLATION CALL FOR UNEXISTING DDNAME - EXPECT RETCODE 4 GENERIC DDNAME ==> XXXXXXXX TRANSLATED DDNAME ==> XXXXXXXX RETURN CODE ==> 00000004
In this example, SYS00003 was the translated ddname for TESTDD for this Server's user session.
iWay Software |