DDNAME Translation in User-Written Subroutines: MSODDX

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.


Top of page

x
MSODDX Calling Environment and Migration From an MVS Server

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.


Top of page

x
Using MSODDX in a Typical Application

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.


Top of page

x
MSODDX Parameters

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).



x
Reference: MSODDX Parameter List

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:

0

Checks whether you are running under the Server. CALLTYPE 0 returns RETCODE=0 if you are running under the Server, or 4 if you are not. WORKAREA is required. GENDD and TRANDD are not referenced.

1

The STANDARD call. You provide the generic ddname (for example, FOCEXEC) in GENDD. The correct ddname to use is returned in TRANDD. WORKAREA is required. The RETCODE is 0 if the ddname is known to the Server, either for this individual user, or as a ddname known globally to all Server users; 4 means the ddname is not known to the Server (TRANDD will be set equal to GENDD so it is not necessary to check RETCODE before using TRANDD).

2

Untranslation. You provide a translated ddname in TRANDD. The generic ddname it came from is returned in GENDD. If TRANDD is not found to be a translated ddname, GENDD is set equal to TRANDD. RETCODE is 0 if TRANDD is a translated ddname; 4 otherwise. WORKAREA is required.

3

Creates a translated ddname. Use only when your user-written subroutine will be performing dynamic allocation. Provide the generic ddname you intend to use in GENDD. If GENDD is not already in use, a new TRANDD is returned and RETCODE is 0. If the ddname in GENDD is already in use, TRANDD is set equal to GENDD, and RETCODE is set to 4. WORKAREA is required.

4

Deletes a translated ddname previously created using a CALLTYPE 3 call. Use when your user-written subroutine will dynamically free the ddname it had previously allocated. Provide the generic ddname in GENDD. If found and removed, RETCODE is 0. RETCODE is 4 if an error was encountered. WORKAREA is required.

(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.



x
ASMDDX - Sample Assembler Exit for MSODDX

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.



x
Syntax: How to Edit GENASDDX

Edit the sample GENASDDX as follows:

  1. Provide a job card.
  2. SET INASMLIB='??????.??????.DATA'

    This sets the Assembler source library. (For our sample, this corresponds to qualif.HOME.DATA.)

  3. SET INASMPGM='??????'

    This sets the Assembler source name. (For our sample, ASMDDX.)

  4. SET INOBJLIB='??????.HOME.DATA'

    This sets the Object library where MSODDXC resides (qualif.HOME.DATA).

  5. SET OUTLIB='??????.??????.LOAD'

    This sets the Output load library.

  6. SET OUTPGM=ASMDDX

    This sets the Output program name.

  7. SET SYSLBLK=3200

    This sets the Object data set block size.

  8. SET PLANG=EDCPMSGE

    This sets the Prelinker message module.

  9. SET LIBPRFX='CEE'

    This sets the LE library prefix.

  10. Provide the entry point <AsmEP> in the LKED step.

    For the sample ASMDDX, <AsmEP> is ASMDDX.

  11. Save GENASDDX and submit the job.


Example: Testing the ASMDDX Sample

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.


Top of page

x
COBDDX - Sample COBOL Exit for MSODDX

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.



x
Syntax: How to Edit GENCPDDX

Edit GENCPDDX as follows:

  1. Provide a job card.
  2. SET INCOBLIB='??????.??????.DATA'

    This sets a COBOL source library. For our sample, this corresponds to qualif.HOME.DATA.

  3. SET INCOBPGM='COBDDX'

    This sets the COBOL source name.

  4. SET INASMLIB='??????.HOME.DATA'

    This sets the Assembler source library where MSODDX2 resides (qualif.HOME.DATA).

  5. SET OUTLIB='??????.??????.LOAD'

    This sets the Output load library.

  6. SET OUTPGM=COBDDX

    This sets the Output program name.

  7. SET LNGPRFX='IBI1.IGY.V2R2M0'

    This sets the COBOL compiler library prefix.

  8. SET SYSLBLK=3200

    This sets the Object data set block size.

  9. SET PLANG=EDCPMSGE

    This sets the Prelinker message module.

  10. SET LIBPRFX='CEE'

    This sets the LE library prefix.

  11. Save GENCPDDX and submit the job.


Example: Testing the COBDDX Sample

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