Finding the z/OS Sysname in CICS

Today I’ve got a simple but neat little tip to share. Have you ever had a need to know which z/OS system your CICS program is running in? I found myself in that situation today, needing a way to programmatically set the hostname in the URL in a CICS web application. The CICS web application could be running in any LPAR. The z/OS system running in each of our LPAR’s has a unique sysname, so if I could access that, I could determine the hostname for that z/OS.

Looking in SYS1.MACLIB(CVT), we see that z/OS has a control block called the CVT (Communications Vector Table) that contains the sysname 340 bytes into it. In the comments at the top of that member, we learn that there is a pointer to the CVT in the PSA (Prefixed Save Area) x’10’ bytes into it. The PSA is easy to find – it is at address 0. So, armed with this info, I wrote the sample code below, which you are welcome to use or incorporate into your own project. If you use this code, just define a PPT for it (if you do not use autoinstall for programs) and point a tranid to the program.

IDENTIFICATION  DIVISION.
PROGRAM-ID.     CVTTEST.

ENVIRONMENT  DIVISION.
DATA  DIVISION.
WORKING-STORAGE  SECTION.

01   WS-PSA-POINTER.
10   PSA-PTR-PIC9        PIC S9(8) COMP-5 VALUE  0.
10   PSA-PTR             REDEFINES PSA-PTR-PIC9 POINTER.

01   SEND-AREA.
10   FILLER              PIC X(1)  VALUE SPACE.
10   FILLER              PIC  X(11) VALUE 'CVTSNAME = '.
10   SA-CVTSNAME         PIC X(8)  VALUE  SPACES.

LINKAGE  SECTION.

01   PSA.
10   FILLER              PIC  X(16).
10   CVT-PTR             POINTER.

01   CVT.
10   FILLER              PIC  X(340).
10   CVTSNAME            PIC  X(8).

EJECT

PROCEDURE  DIVISION.

100-MAINLINE.

SET ADDRESS OF PSA TO  PSA-PTR.
SET ADDRESS OF CVT TO  CVT-PTR.

MOVE CVTSNAME TO  SA-CVTSNAME.

EXEC CICS SEND  FROM(SEND-AREA)
LENGTH(LENGTH OF  SEND-AREA)
END-EXEC.

999-RETURN.

EXEC CICS  RETURN
END-EXEC.

GOBACK.

CALL or LINK?

It’s an old question … In my CICS program, should I invoke a subprogram using a standard COBOL CALL, or should I use the EXEC CICS LINK API?

The traditional answer was, “LINK is easier to debug, CALL is more efficient.” However, there have been some changes in the CICS environment in recent years that blur the efficiency line and add other variables to consider.

The reason that LINK was considered easier to debug is that CALLs are “invisible” to CICS – you won’t see the transfer take place if using CEDF to debug. However, modern debug tools (e.g., Xpediter) have no problems showing CALLs, and virtually all shops use such a tool these days. So, if CALLs are more efficient and there is no debugging advantage to LINK, why use the CICS API?

The biggest advantage is probably the fact that using LINK can send control over to another CICS region. Since CICS has minimal involvement with a CALL, the processing stays in the same region; use LINK, and the program could be invoked in the same region, or it may be statically or dynamically routed to another region. If the program has special resource needs that are best served (or only served) in a particular region, statically route its execution to that region; if load balancing, let WLM route it to the least busy region. In my mind, those are huge. Other advantages include the fact that when using LINK, CICS will handle DATALOCATION (any/below) and EXECKEY (user/CICS) differences, and it will handle mode switches between THREADSAFE/QUASIRENT CONCURRENCY and OPENAPI/CICSAPI.

Another consideration that used to exist was that more than 32K could be passed in a CALL, but COMMAREA used to pass data in a LINK have that limit. However, use of CHANNELS and CONTAINERS overcome this limitation starting in CICS/TS 3.1.

My general rule of thumb is this … If invoking a subprogram that does not do “CICS stuff” (i.e., has no EXEC CICS statements), the same subprogram could easily be CALLed from batch, so use a COBOL CALL so that the interfaces are consistent. If it does “CICS stuff”, then use LINK. But that’s just a rule of thumb – if efficiency concerns override the advantages of using LINK, then it’s perfectly fine to CALL a program that has “CICS stuff” in. If there are issues with CONCURRENCY or other items mentioned above, using LINK to invoke a program with no “CICS stuff” is perfectly fine, too. Use the tool that is best fitted for the situation.

New Section in COBOL Compile Listings

Enterprise COBOL for z/OS 4.1 offers several new features, including enhanced DB2 support (mostly for DB2 V9) and the ability to take advantage of the z/OS XML System Services parser. But what caught my eye was something that every shop can take advantage of. There is a new section in COBOL compiler listings that shows from which library each copybook was pulled, and even when each was created and last changed. To find this section, do a “find” on “COPY/BASIS” while viewing the listing. Be sure that the compile was done with the XREF option set on. This new feature should help if there is any confusion regarding where a copybook came from that was used in the compiling of a program.