PROGRAM

The PROGRAM statement marks the start of a Jazz program, and describes its environment. You may have only one PROGRAM statement in a program, and it is normally the first statement in the program, although it may be preceded by one or more DEFINE statements. It may be stored in a Copy-book, in which case the COPY statement must be the first statement in the program.

Its format is: -

PROGRAM program-name [Option]…

for example

PROGRAM ShowMenu CICS;

Program-name

It must follow the rules for external names: i.e. be 8 characters or less, and not contain hyphens or special characters like “$”. It must be unique: it cannot be the same as any other “Level 1 name” (Definition names etc).

General Options – BATCH/CICS, REPORT

BATCH

(default) This specifies that the program is to run as a batch program, being initiated by JCL and producing a report, copying a file, or sequentially updating a file. With BATCH your program can process physical-sequential files (types F, FB, V, VB, and U) as well as VSAM and SQL that can also be processed by CICS. The program cannot use CICS options like INSCREEN or SERVICE, nor statements like SEND and ACCEPT that deal with screens, nor INVOKE or REPLY.

EZT

This is automatically added to the PROGRAM statement if you generate a program with New/Logic/Batch, and you check Enable EZT Conversion.

If EZT is present then the workbench [Screen] button, which is inactive for normal batch programs, is active and is labelled [EZT Conv], and the [Services] button is active and is labelled [LProc].

When clicked, [EZT Conv] opens the “Easytrieve Conversion Notepad”, which is a Jazz Workbench modified to handle conversion from Easytrieve. See Easytrieve Conversion (jazzsoftware.co.nz) for more information.

When clicked, [LProc] opens a dialog to create routines to load searchable tables.

You can also write this option manually. If so, you should also add the position markers that indicate where code should be copied, or else code may not be copied back from the Easytrieve Conversion Notepad, or copied into the wrong place. Position markers are: -

*# Copy Files here ==> Place this early in the program, after other DEFINE and COPY statements.

*#Copy Process logic here ==> Place this within the PROCESS loop

*#Copy Routines here ==> Place this after the PROCESS loop

If you’re creating these markers manually, copy them exactly as shown.

CICS

Specifies that the program is an on-line program controlled by CICS. CICS is assumed if the PROGRAM statement contains any of the options implying a Classical CICS (3270-type screen) program – INSCREEN, TRANSID, EXIT, COMMAREA or NOCLEAR – or a web service – SERVICE, REPLY, CHANNEL or CONTAINER.

If CICS is specified then the program may not use physical-sequential files (types F, FB, V, VB, and U), nor PRINT or REPORT statements.

REPORT

Specifies that the program has a report structure: a process loop reading an input file, using a control break structure invoking $Rpt-xxxx routines, and producing a report. REPORT is currently used only for BATCH programs, but a future development may allow it to be used in web service programs also.

REPTS

If the batch program was generated with [ü] Combine Repts checked, then the PROGRAM statement will be generated with this option: -

PROGRAM Batch1 BATCH REPTS SYSPRINT;

This option can also be written manually. Its effect is to mimic the behaviour of Easytrieve Programs, in which all reports are produced on a single DD using the DDName given (SYSPRINT in this example – this is the default). The generated COBOL from this program will write the first report directly to

//SYSPRINT DD SYSOUT=*

Other reports are written to work files, e.g.
//REPORT2 DD DSNAME=&&REPORT2,DISP=(NEW,DELETE)

On program termination REPORT2 etc are copied to SYSPRINT, so that a single SYSOUT is produced with each report printed in order, with separator pages.

Classical CICS Options.

The following options are used if the program uses 3270 screens, and communicates through a COMMAREA (communications area). They are invalid if BATCH is specified, and they conflict with Web Service Options.

INSCREEN(screen-name)

e.g. INSCREEN(Scrn1)

INSCREEN lets you specify that the program will be initiated by the system after the operator has responded to the screen named, and subsequent ACCEPT statements within the program may process data from the screen.

INSCREEN implies that the program is an on-line program, and so the CICS option is required. Jazz checks that the screen-name exists in the Jazz SCREENLIB; if it does not, then you can invoke the screen editor to create the screen.

Click on INSCREEN and the record layout can be displayed as a normal DEFINE statement. You should not edit this: if you want to make changes you should use the screen editor, accessed through the [Screen] button.

TRANSID(Transaction-id)

This specifies the transaction ID that will be used to initiate this program. Transaction ID’s must be 4 characters or less. The transaction-id is used: -

1. If the screen template contains parameter value @TRN then this will be substituted by the transaction ID

2. If the program terminates without specifying another transaction id, then this value is used. The program will be restarted when a response is received.

NOTE: the transaction ID defined to CICS, for example with the CEDA command, must correspond to the PROGRAM statement. Jazz cannot check this. If you wrote

PROGRAM CICS1 TRANSID (TRNX) …

and then define to CICS
DEF TRANS(TRN1) PROGRAM(CICS1) GROUP(CICSG)

results will be incorrect. You must either write TRANSID (TRN1) in the PROGRAM statement, or DEF TRANS(TRNX) in the CEDA command.

COMMAREA(Commarea-name)

Jazz always generates pseudo-conversational programs, so that when it SENDs a screen or exits in any other way the program is terminated. All data that is needed from one part of the program to another therefore has to be saved explicitly in a communication area. If you like you can think of COMMAREA as a kind of parameter. The Commarea name, like the screen name of the INSCREEN option, is a definition that must exist in the Jazz copy library.

Click on COMMAREA and the record layout is displayed, and can be edited.

COMMAREA may also be used with Web Service Programs.

EXIT(Program-name)

This specifies a program that is initiated when this program exits without SENDing a screen or through an explicit EXIT statement. Its main use is in specifying what is to happen on PF3/PF12 exit.

NOCLEAR

This option is only valid if the INSCREEN option is present.

With PROGRAM …. INSCREEN(screen) your program is going to start by reading the input screen, then deciding what to do with it. Jazz will automatically insert logic that will: -

· Test that a message has been received with a length > 0

· If a zero-length message has been received, send back an empty screen (displaying constants, but nothing in any of the data fields) with options so that this program will be re-started when the operator responds to it.

You usually want the same behaviour if the operator presses the Clear key, so Jazz creates logic as if you had written

IF EIBCALEN = 0 | EIBAID = DFHCLEAR THEN

SEND screen ERASE;

END IF;

If your PROGRAM statement includes NOCLEAR then the second part of the condition is omitted, and your program effectively contains

IF EIBCALEN = 0 THEN

SEND screen ERASE;

END IF;

Web Service Options

The following options are used if the program provides a web service that may be invoked externally, or if it processes the reply to a web service. If any of these options are used, then CICS is assumed. They may not be used if BATCH is specified. They conflict with Classical CICS Options except for COMMAREA.

WEBSERVICE [ServiceName]

Use this option when the program is to be invoked as a web service. If no name is given, then “MySvce” is assumed, e.g.

PROGRAM GetName WEBSERVICE;

is equivalent to

PROGRAM GetName WEBSERVICE MySvce;

There may be several operations at this web service: this PROGRAM statement will refer to operation MySvce-GetName

The operation name (= program name) must be unique within the service, and the combination ServiceName-OperationName must be unique within your project. The implication of this is that there is only one way of invoking program GetName, and that is as a service request to MySvce-GetName.

Right-click on WEBSERVICE and the record definitions for MySvce-GetName will be opened. It can be edited.

CONTAINER [ContainerName] | COMMAREA CommareaName

Use CONTAINER if a web service provider communicates via a CHANNEL, and COMMAREA if it communicates via a COMMAREA. COMMAREA is only valid for WSDL services, and is provided by IBM for compatibility with old CICS programs, but CONTAINER is recommended for new programs. With Micro Focus Enterprise the container name must be DFHWS-DATA. Thus

PROGRAM GetTime WEBSERVICE MySvce COMMAREA GetTimeC;

reads the web service input message from commarea, and the REPLY statement sends the output message using commarea also. By comparison,

PROGRAM GetTime WEBSERVICE MySvce CONTAINER CGetTime;

will read the input message from container CGetTime using the default channel, and will put the reply there also.

WSDL | JSON

WSDL causes Jazz to create a SOAP(Simple Object Access Protocol) message communicating with WSDL (Web Services Description Language).

JSON causes Jazz to create a REST (Representational State Transfer) message communicating with JSON (Javascript Object Notation).

Apart from this difference in the PROGRAM statement there should be no other differences within the Jazz program.

HTTP | HTTPS

Use HTTPS to have the DFHLS2WS step (generated into the job when the program is processed) specify a URI such as

URI=https://192.86.32.59:9015/manajazz/gettim

Otherwise this will include (for example)

URI=http://192.86.32.59:9014/manajazz/gettim

There is actually no difference in the COBOL, and you could change from one to the other if you were manually setting up your web service.

REPLY ServiceName-OperationName

This option isn’t yet implemented. Although it may parse and generate COBOL this has not been tested.

Use this option when the program is to be invoked to process the reply from some other web service. For example, the first SOATest program that we wrote invokes web service SOATest1 with: -

PROGRAM WST1 INSCREEN(WST1S) CICS TRANSID(TRW1);

DEFINE Wrk DATA(

Name VARCHAR (20),

Result VARCHAR (70));

ACCEPT (WST1S.Name);

COPY SOATst-SOATest1 WEBSERVICE;

INVOKE SOATst-SOATest1(Wrk.Name) REPLY(Wrk.Result, Wrk.Name);

SEND WST1S(WST1S.Result);

This was a conversational program, with the advantages and disadvantages implied by this program structure. We could have written this as a pair of programs to create a pseudo-conversational structure by terminating the program at the INVOKE, and writing a separate program to process the reply: -

PROGRAM WST1A INSCREEN(WST1S) CICS TRANSID(TRW1);

DEFINE Wrk DATA(

Name VARCHAR (20),

Result VARCHAR (70));

ACCEPT (WST1S.Name);

COPY SOATst-SOATest1 WEBSERVICE;

INVOKE SOATst-SOATest1(Wrk.Name);

and separately

PROGRAM WST1B REPLY SOATst-SOATest1;

COPY WST1S;

ACCEPT (WST1A.Result = $Reply.Result, WST1A.Name = $Reply.Name);

SEND WST1S;

Right-click on REPLY and the record definition for the web service reply can be viewed. It should not be edited except from the program that created this service.

Database options

If your program processes a SQL database, then the PROGRAM statement should include a DATABASE option: -

PROGRAM SQLexml2 BATCH DATABASE mydb2 DB2;

DATABASE name

This gives the name of the database. There must be a member of the LocalJCL folder (refer Configuration) with type .JZL or .JCL with this name: e.g. with this example Jazz checks that the folder contains either mydb2.jzl or mydb2.jcl. JZL is “Jazz-format JCL” – it is like standard z/OS JCL except that you can ignore line boundaries and use @xxx Jazz parameters (as well as standard z/OS &parameters). This JZL (or JCL) member is inserted into the run steps of batch jobs.

Database Type

You must specify the database type as DB2, ORACLE, or SQL (meaning SQL Server) so that Jazz can take care of dialect differences. Currently this is mostly a comment, and the only difference is that, when generating a SELECT … INTO for a batch GET, a situation where the GET should return only one record, then for DB2 and ORACLE Jazz will generate

SELECT …. FETCH FIRST ROW ONLY

while for SQL Jazz will generate

SELECT TOP 1 ….

Initial testing is with DB2, and Jazz has not yet been tested with the other database types.