Chapter 4. PL/I preprocessors. IBM Version 8.5

Chapter 4. PL/I preprocessors

The PL/I compiler allows you to select one or more of the integrated preprocessors as required for use in your program. You can select the include preprocessor, macro facility, the SQL preprocessor, or the CICS preprocessor and the order in which you would like them to be called.

v

The include preprocessor processes special include directives and incorporates external source files.

v

The macro facility, based on %statements and macros, modifies your source program.

v

The SQL preprocessor modifies your source program and translates EXEC SQL statements into PL/I statements.

v

The CICS preprocessor modifies your source program and translates EXEC CICS statements into PL/I statements.

Each preprocessor supports a number of options to allow you to tailor the processing to your needs. You can set the default options for each of the preprocessors by using the corresponding attributes in the configuration file.

Include preprocessor

The include preprocessor allows you to incorporate external source files into your programs by using include directives other than the PL/I directive %INCLUDE.

The following syntax diagram illustrates the options supported by the INCLUDE preprocessor:

PP ( INCLUDE ( '

ID(<directive>)

' ) )

ID

Specifies the name of the include directive. Any line that starts with this directive as the first set of nonblank characters is treated as an include directive.

The specified directive must be followed by one or more blanks, an include member name, and finally an optional semicolon. Syntax for ddname(membername) is not supported.

In the following example, the first include directive is valid and the second one is not:

++include payroll

++include syslib(payroll)

Examples

This first example causes all lines that start with -INC (and possibly preceding blanks) to be treated as include directives: pp( include( ’id(-inc)’))

This second example causes all lines that start with ++INCLUDE (and possibly preceding blanks) to be treated as include directives: pp( include( ’id(++include)’))

© Copyright IBM Corp. 1998, 2012

147

Include preprocessor

Include preprocessor options environment variable

You can set the default options for the include preprocessor by using the

IBM.PPINCLUDE environment variable. See “IBM.PPINCLUDE” on page 22.

Macro preprocessor

Macros allow you to write commonly used PL/I code in a way that hides implementation details and the data that is manipulated, and exposes only the operations. In contrast with a generalized subroutine, macros allow generation of only the code that is needed for each individual use.

The macro preprocessing facilities of the compiler are described in the

PL/I

Language Reference

manual.

You can invoke the macro preprocessor by specifying either the MACRO option or the PP(MACRO) option. You can specify

PP(MACRO) without any options or with options from the list below.

The defaults for all these options cause the macro preprocessor to behave the same as the OS PL/I V2R3 macro preprocessor.

If options are specified, the list must be enclosed in quotes (single or double, as long as they match) ; for example, to specify the FIXED(BINARY) option, you must specify PP(MACRO(’FIXED(BINARY)’)).

If you want to specify more than one option, you must separate them with a comma and/or one or more blanks. For example, to specify the CASE(ASIS) and

RESCAN(UPPER) options, you can specify PP(MACRO(’CASE(ASIS)

RESCAN(UPPER)’)) or PP(MACRO("CASE(ASIS),RESCAN(UPPER)")). You may specify the options in any order.

Macro preprocessor options

The macro preprocessor supports the following options:

CASE

This option specifies if the preprocessor should convert the input text to uppercase.

CASE (

UPPER

ASIS )

ASIS

the input text is left "as is".

UPPER

the input text is to be converted to upper case.

FIXED

This option specifies the default base for FIXED variables.

FIXED (

DECIMAL

BINARY )

DECIMAL

FIXED variables will have the attributes REAL FIXED DEC(5).

148

PL/I for Windows Programming Guide

Macro facility

BINARY

FIXED variables will have the attributes REAL SIGNED FIXED BIN(31).

INCONLY

This option specifies that the preprocessor should process only %INCLUDE and %XINCLUDE statements. When this option is in effect, you may use neither INCLUDE or XINCLUDE as a macro v procedure name v statement label v variable name

NOINCONLY

This option specifies that the preprocessor should process all preprocessor statements and not only %INCLUDE and %XINCLUDE statements. This option and the INCONLY option are mutually exclusive, and for compatibility,

NOINCONLY is the default.

NAMEPREFIX

This option specifies that the names of preprocessor procedures and variables must start with the specified character.

NAMEPREFIX (

character

)

The character should be specified "as is" and should not be enclosed in quotes.

NONAMEPREFIX

This option specifies that the names of preprocessor procedures and variables are not required to start with one particular character. NONAMEPREFIX is the default.

RESCAN

This option specifies how the preprocessor should handle the case of identifiers when rescanning text.

RESCAN (

ASIS

UPPER )

UPPER

rescans will not be case-sensitive.

ASIS

rescans will be case-sensitive.

To see the effect of this option, consider the following code fragment

%dcl eins char ext;

%dcl text char ext;

%eins = ’zwei’;

%text = ’EINS’; display( text );

%text = ’eins’; display( text );

When compiled with PP(MACRO('RESCAN(ASIS)')), in the second display statement, the value of text is replaced by eins

, but no further replacement occurs since under RESCAN(ASIS), eins does not match the macro variable eins since the former is left asis while the latter is uppercased. Hence the following text would be generated

Chapter 4. PL/I preprocessors

149

Macro facility

DISPLAY( zwei );

DISPLAY( eins );

But when compiled with PP(MACRO('RESCAN(UPPER)')), in the second display statement, the value of text is replaced by eins

, but further replacement does occur since under RESCAN(UPPER), eins does match the macro variable eins since both are uppercased. Hence the following text would be generated

DISPLAY( zwei );

DISPLAY( zwei );

In short: RESCAN(UPPER) ignores case while RESCAN(ASIS) does not.

You can set the default options for the macro preprocessor by using the set

IBM.PPMACRO

command.

Macro facility options environment variables

You can set the default options for the macro facility by using the IBM.PPMACRO

environment variable. See “IBM.PPMACRO” on page 22.

SQL preprocessor

You can use dynamic and static EXEC SQL statements in PL/I applications. Before you can take advantage of EXEC SQL support, you must have installed IBM DB2

Universal Database (herinafter referred to as DB2) for Windows.

Workstation PL/I products support most of the function in DB2 and increased function will be added in each successive release. If you specify newer DB2 functions while using a downlevel DB2 product, warning messages are generated and those newer options are ignored.

Programming and compilation considerations

You need to consider specific options when using the PL/I SQL preprocessor. The

PL/I for Windows SQL preprocessor does not support variables that have either the NONNATIVE or the HEXADEC attributes.

When you have EXEC SQL statements in your PL/I source program, use the

PP(SQL) option to process those statements: pp(sql(’

option-string

’))

In the preceding example, '

option-string

' is a character string enclosed in quotes. For example, pp(sql(’dbname(Sample)’) tells the preprocessor to work with the

SAMPLE database.

If you are using EXEC SQL statements in your program, you must specify the SQL library in addition to the other link libraries in the linking command, for example: ilink myprog.obj db2api.lib

All PL/I statements must be syntactically correct, because the SQL preprocessor scans the source looking for EXEC SQL statements, DECLARE statements, and statements that delimit blocks of declarations. If a statement is coded incorrectly, this might mislead the preprocessor when looking for the END statement to a

BEGIN, DO, PACKAGE, PROCEDURE, or SELECT statement, and that can cause the preprocessor to be unable to resolve some host variable references correctly.

150

PL/I for Windows Programming Guide

SQL preprocessor

If the source uses %INCLUDE or other macro statements, invoke the MACRO preprocessor before the SQL preprocessor.

The SQL preprocessor supports DBCS in the same manner as the PL/I compiler does. When the GRAPHIC PL/I compiler option is in effect, some source language elements can be written using DBCS and SBCS characters. In particular, you can use DBCS characters in the source program in the following places: v

Inside comments v As part of statement labels and identifiers v

In G or M literals

The following restrictions apply to the use of PL/I built-in functions, compiler options, and statements when you program and compile SQL statements: v

When EXEC SQL statements are translated to PL/I, the following built-in functions might be included in the generated code. If you use any of the following built-in functions as the names of elements in structures, you must also explicitly declare them as BUILTIN:

– ADDR

– LENGTH

– MAXLENGTH

– PTRVALUE

– SYSNULL v

You must not use PL/I type functions, such as BIND(: t, p :), in EXEC SQL statements.

v

When compiling with the preprocessor, you must not use these compiler options:

– DFT(EBCDIC)

– DFT(HEXADEC) v

Do not use DECLARE STATEMENT statements in SQL queries, because the PL/I preprocessor always ignores these statements.

SQL Users

You must have DB2 Universal Database for Windows installed and started before you can compile a program containing EXEC SQL statements. To find out how to install DB2, refer to database installation guide for the platform you are using.

You can start the database manager by issuing the following at a command prompt: db2start

SQL preprocessor options

The following syntax diagram illustrates all of the options supported by the SQL preprocessor.

PP ( SQL ( ' DBNAME (

dbname

)

BLOCK ( UNAMBIG )

ALL

NO

Chapter 4. PL/I preprocessors

151

SQL preprocessor

NOBIND

BIND

(

bindname

)

CALL_RESOLUTION ( IMMEDIATE )

DEFERRED

COLLECTION (

schema-name

) CONNECT ( 1 )

2

DATETIME ( DEF )

USA

EUR

ISO

JIS

LOC

DBUID(

userid

) DBPWD(

password

)

NODECK

DECK

,

DEPRECATE ( STMT (

EXPLAIN

GRANT

REVOKE

SET_CURRENT_SQLID

NOINCONLY

INCONLY DISCONNECT ( EXPLICIT

AUTOMATIC

CONDITIONAL

)

) )

INSERT ( DEF )

BUF

ISOLATION ( CS )

RR

RS

UR

ONEPASS

TWOPASS OWNER (

authorization-id

)

PLAN

(

planname

)

NOPLAN

NOPLANSYNTAX

QUALIFIER (

qualifier-name

)

152

PL/I for Windows Programming Guide

SQL preprocessor

SQLFLAG ( MVSDB2V23 )

MVSDB2V31

MVSDB2V41

SQLRULES ( DB2 )

STD

SYNCPOINT ( ONEPHASE )

TWOPHASE

NONE

TBQUAL (

table-qualifier-name

)

VALIDATE ( BIND )

RUN

VERSION (

version-id

)

AUTO

Abbreviations: DB, BLK, CRESO, DT, ISOL, ON, TW, D, ND, INS, COL, CON,

DISC, SQLR, SYNC

DBNAME

Specifies the original or alias name of a database. This option directs the preprocessor to process the SQL statements against the specified database. If you omit this option or do not specify a database name, the preprocessor uses the default database if an implicit connect is enabled. The default database is specified by the environment variable DB2DBDFT. Further information is available in your DB2 documentation.

The preprocessor must have a database to work with or an error occurs.

BLOCK

Specifies the type of record blocking to be used and how ambiguous cursors are to be treated. The valid values for this option are:

UNAMBIG

Blocking occurs for read-only cursors, those that are not specified as FOR

UPDATE OF, have no static DELETE WHERE CURRENT OF statements, and have no dynamic statements. Ambiguous cursors can be updated.

ALL

Blocking occurs for read-only cursors, those that are not specified as FOR

UPDATE OF, and for which no static DELETE WHERE CURRENT OF statements are executed. Ambiguous and dynamic cursors are treated as read-only.

NO

No blocking is done on any cursors in the package. Ambiguous cursors can be updated.

BIND or NOBIND

Determines whether or not a bind file bindname is created. The bind file has an extension .BND and is saved either in the current directory or the directory specified by the IBM_BIND environment variable. If you do not specify a bindname, the name defaults to the name of the input source file.

CALL_RESOLUTION

Determines whether the CALL statement will be executed as an invocation of

Chapter 4. PL/I preprocessors

153

SQL preprocessor

the deprecated sqleproc() API or as a normal SQL statement. Note that

SQL0204 will be issued if the precompiler fails to resolve the procedure on a

CALL statement with CALL_RESOLUTION IMMEDIATE.

IMMEDIATE

The CALL statement will be executed as a normal SQL statement. This is the default.

DEFERRED

The CALL statement will be executed as an invocation of the deprecated sqleproc() API.

COLLECTION

Specifies an eight character collection identifier for the package.

schema-name

Eight character identifier.

There is no default value for the COLLECTION option. If the COLLECTION is specified, a schema-name must also be provided.

CONNECT

Specifies the type of CONNECT that is made to the database.

1

Specifies that a CONNECT command is processed as a type 1 CONNECT.

This is the default setting.

2

Specifies that a CONNECT command is processed as a type 2 CONNECT.

The default option value is CONNECT(1). The following option strings evaluate to CONNECT(1): CON, CONNECT, CON(), and CONNECT().

DATETIME

Determines the date and time format used when date and time fields are assigned to string representations in host variables. The following three-letter abbreviations are valid for the variable

location

:

DEF

Use the date/time format associated with the country code of the database. This is also the default if DATETIME is not specified.

USA

IBM standard for U.S. form.

Date format: mm/dd/yyyy

Time format: hh:mm xM (AM or PM)

EUR

IBM standard for European form.

Date format: dd.mm.yyyy

ISO

Time format: hh.mm.ss

International Standards Organization.

Date format: yyyy-mm-dd

Time format: hh.mm.ss

JIS

Japanese Industrial Standards.

Date format: yyyy-mm-dd

Time format: hh:mm:ss

LOC

Local form, not necessarily equal to DEF

DBUID and DBPWD

Allows you to specify a

userid

and

password

for those database managers which require that these values be supplied when a remote connection is attempted.

For example, these values might be required during a compile against a remote database resident on a Windows server.

The options DBUID and DBPWD can be in either case, but the values of

userid

(maximum length is 8 characters) and

password

(maximum length is 18 characters) are case sensitive.

154

PL/I for Windows Programming Guide

SQL preprocessor

The userid and password are only used by the SQL preprocessor to connect to the database manager during the compile process. When the application connects during execution, the userid and password for that connect must be provided on the EXEC SQL CONNECT statement in the program.

DECK or NODECK

This option specifies that the SQL preprocessor output source is written to a file with the extension .DEK and the file is put the current directory.

DEPRECATE

This option indicates that the preprocessor flags the specified statements as deprecated.

STMT

Specifies a list of statements that the preprocessor should flag as deprecated. The list can be empty.

EXPLAIN

The EXPLAIN SQL statement.

GRANT

The GRANT SQL statement.

REVOKE

The REVOKE SQL statement.

SET_CURRENT_SQLID

The SET CURRENT SQLID SQL statement.

The default option is: DEPRECATE(STMT())

DISCONNECT

Specifies the type of DISCONNECT that is made to the database.

EXPLICIT

Specifies that only database connections that have been explicitly marked for release by the RELEASE statement are disconnected at commit. This is the default setting.

AUTOMATIC

Specifies that all database connections are disconnected at commit.

CONDITIONAL

Specifies that the database connections that have been marked RELEASE or have no open WITH HOLD cursors are disconnected at commit.

The default option value is DISCONNECT(EXPLICIT). The following option strings evaluate to DISCONNECT(EXPLICIT): DISC, DISCONNECT, DISC(),

DISCONNECT().

INCONLY or NOINCONLY

Determines whether or not the SQL preprocessor should process only EXEC

SQL INCLUDE statements.

When INCONLY is specified, no code is generated by the SQL preprocessor and all of the EXEC SQL INCLUDE statements are expanded. When INCONLY is specified, other options cannot be specified.

When NOINCONLY is specified, the SQL preprocessor processes all statements and generates code. INCONLY and NOINCONLY are mutually exclusive, and for compatibility, NOINCONLY is the default.

Chapter 4. PL/I preprocessors

155

SQL preprocessor

INSERT

Requests that the data inserts be buffered to increase performance on the

DB2/6000 Parallel Edition server.

DEF

Use standard INSERT with VALUES execution. This is the default setting.

BUF

Use buffering when executing INSERTs with VALUES.

Note:

This option can only be used when precompiling against a DB2 Parallel

Edition server. If INSERT is used against a DB2 V1.x server, it is ignored and a warning message is issued. If INSERT is used against a DB2 V2.x

server, it is ignored, a warning message is issued, and the option is added to the bind file.

ISOLATION

Determines how far a program bound to this package can be isolated from the effect of other executing programs.

CS

RR

RS

Specifies Cursor Stability as the isolation level.

Repeatable readSpecifies Repeatable Read as the isolation level.

Specifies Read Stability as the isolation level. Read Stability ensures that the execution of SQL statements in the package is isolated from

UR

other application processes for rows read and changed by the application.

Specifies Uncommitted Read as the isolation level.

ONEPASS or TWOPASS

ONEPASS is the default and indicates that host variables must be declared before use. Use of TWOPASS indicates that host variables do not need to be declared before use.

OWNER

Designates a 30-character

authorization-id

for the package owner. The owner must have the privileges required to execute the SQL statements contained in the package. Only a user with SYSADM or DBADM authority can specify an

authorization-id

other than the user ID. The default value is the primary

authorization-id

of the precompile/bind process. SYSIBM, SYSCAT, and

SYSSTAT are not valid values for this option.

PLAN, NOPLAN, or NOPLANSYNTAX

Determines whether or not an access plan

planname

is created. If you do not specify a planname, the name defaults to the name of the input source file.

If you specify NOPLANSYNTAX, no plan is created and a syntax check is performed against DB2 Version 2.1 syntax.

QUALIFIER

Provides an 30-character implicit

qualifier-name

for unqualified objects contained in the package. The default is the owner's authorization ID, whether or not owner is explicitly specified.

SQLFLAG

Identifies and reports on deviations from SQL language syntax specified in this option. If this option is not specified, the flagger function is not invoked.

Further information is available in your DB2 documentation.

MVSDB2V23

SQL statements are checked against the MVS DB2 V2.3 SQL language syntax. This is the default setting.

156

PL/I for Windows Programming Guide

SQL preprocessor

MVSDB2V31

SQL statements are checked against the MVS DB2 V3.1 SQL language syntax.

MVSDB2V41

SQL statements are checked against the MVS DB2 V4.1 SQL language syntax.

SQLRULES

Specifies whether type 2 CONNECTs should be processed according to the

DB2 rules or the Standard (STD) rules based on ISO/ANS SQL92.

DB2

Allows the use of the SQL CONNECT statement to switch the current connection to another established (dormant) connection. This is the default setting.

STD

Allows the use of the SQL CONNECT statement to establish a new connection only. The SQL SET CONNECTION must be used to switch to a dormant connection.

The default option value is SQLRULES(DB2). The following option strings evaluate to SQLRULES(DB2): SQLR, SQLRULES, SQLR(), SQLRULES().

SYNCPOINT

Specifies how commits or rollbacks are coordinated among multiple database connections.

ONEPHASE

Specifies that no Transaction Manager (TM) is used to perform a two-phase commit. A one-phase commit is used to commit the work done by each database in multiple database transactions. This is the default setting.

TWOPHASE

Specifies that the TM is required to coordinate two-phase commits among those databases that support this protocol.

NONE

Specifies that no TM is used to perform a two-phase commit, and does not enforce single updater, multiple reader. A COMMIT is sent to each participating database. The application is responsible for recovery if any of the commits fail.

The default option value is SYNCPOINT(ONEPHASE). The following option strings evaluate to SYNCPOINT(ONEPHASE): SYNC, SYNCPOINT, SYNC(),

SYNCPOINT().

TBQUAL

Provides an 8-character implicit

table-qualifier-name

for unqualified objects contained in the package.

VALIDATE

Determines when the database manager checks for authorization errors and object not found errors. The package owner authorization ID is used for validity checking.

BIND

Validation is performed at precompile/bind time. If all objects do not exist, or all authority is not held, error messages are produced. If

sqlerror

Chapter 4. PL/I preprocessors

157

SQL preprocessor continue

is specified, a package/bind file is produced despite the error message, but the statements in error are not executable.

RUN

Validation is attempted at bind time. If all objects exist, and all authority is held, no further checking is performed at execution time. If all objects do not exist, or all authority is not held at precompile/bind time, warning messages are produced, and the package is successfully bound, regardless of the

sqlerror continue

option setting. However, authority checking and existence checking for SQL statements that failed these checks during the precompile/bind process can be redone at execution time.

VERSION

Defines the version identifier for a package. If this option is not specified, the package version will be "" (the empty string).

version-id

Specifies a version identifier that is any alphanumeric value, $, #, @, _, -, or

., up to 64 characters in length.

AUTO

The version identifier will be generated from the consistency token. If the consistency token is a timestamp (it will be if the LEVEL option is not specified), the timestamp is converted into ISO character format and is used as the version identifier.

SQL preprocessor options environment variable

You can set the default options for the SQL Preprocessor by using the IBM.PPSQL

environment variable. See “IBM.PPSQL” on page 22.

SQL preprocessor BIND environment variables

If the BIND option is specified, the SQL preprocessor creates a bind file in the current directory for the program you compile. You can change the destination of the output file by setting the IBM.BIND environment variable, for example: set ibm.bind=C:\bindlib

The SQL bind output file has the same name as the primary input file, unless otherwise specified, and an extension of BND.

Coding SQL statements in PL/I applications

You can code SQL statements in your PL/I applications using the language defined in

SQL Reference, Volume 1 and Volume 2

. Specific requirements for your SQL code are described in the sections that follow.

Defining the SQL communications area

A PL/I program that contains SQL statements must include an SQL

communications area (SQLCA) As shown in Figure 1 on page 159 part of an

SQLCA consists of an SQLCODE variable and an SQLSTATE variable.

v

The SQLCODE value is set by the Database Manager after each SQL statement is executed. An application can check the SQLCODE value to determine whether the last SQL statement was successful.

v

The SQLSTATE variable can be used as an alternative to the SQLCODE variable when analyzing the result of an SQL statement. Like the SQLCODE variable, the

SQLSTATE variable is set by the Database Manager after each SQL statement is executed.

158

PL/I for Windows Programming Guide

SQL preprocessor

The SQLCA should be included by using the SQL INCLUDE statement: exec sql include sqlca;

The SQLCA must not be defined within an SQL declare section. The scope of the

SQLCODE and SQLSTATE declaration must include the scope of all SQL statements in the program.

Dcl

1 Sqlca,

2 sqlcaid

2 sqlcabc

2 sqlcode

2 sqlerrm char(8), /* Eyecatcher = ’SQLCA ’*/ fixed binary(31), /* SQLCA size in bytes = 136 */ fixed binary(31), char(70) var,

/* SQL return code */

/* Error message tokens */

2 sqlerrp char(8), /* Diagnostic information */

2 sqlerrd(6) fixed binary(31), /* Diagnostic information */

2 sqlwarn,

3 sqlwarn0 char(1),

/* Warning flags */

3 sqlwarn1 char(1),

3 sqlwarn2 char(1),

3 sqlwarn3 char(1),

3 sqlwarn4 char(1),

3 sqlwarn5 char(1),

3 sqlwarn6 char(1),

3 sqlwarn7 char(1),

2 sqlext,

3 sqlwarn8 char(1),

3 sqlwarn9 char(1),

3 sqlwarna char(1),

3 sqlstate char(5); /* State corresponding to SQLCODE */

Figure 1. The PL/I declaration of SQLCA

Defining SQL descriptor areas

The following statements require an SQLDA:

PREPARE

statement-name

INTO

descriptor-name

FROM

host-variable

EXECUTE...USING DESCRIPTOR

descriptor-name

FETCH...USING DESCRIPTOR

descriptor-name

OPEN...USING DESCRIPTOR

descriptor-name

DESCRIBE

statement-name

INTO

descriptor-name

Unlike the SQLCA, there can be more than one SQLDA in a program, and an

SQLDA can have any valid name. An SQLDA should be included by using the

SQL INCLUDE statement: exec sql include sqlda;

The SQLDA must not be defined within an SQL declare section.

Chapter 4. PL/I preprocessors

159

SQL preprocessor

Dcl

1 Sqlda based(Sqldaptr),

2 sqldaid

2 sqldabc

2 sqln

2 sqld char(8), /* Eye catcher = ’SQLDA ’ */ fixed binary(31), /* SQLDA size in bytes=16+44*SQLN*/ fixed binary(15), /* Number of SQLVAR elements*/ fixed binary(15), /* # of used SQLVAR elements*/

2 sqlvar(Sqlsize refer(sqln)), /* Variable Description

3 sqltype fixed binary(15), /* Variable data type

*/

*/

3 sqllen fixed binary(15), /* Variable data length

3 sqldata pointer,

*/

/* Pointer to variable data value*/

3 sqlind pointer,

3 sqlname char(30) var ; dcl Sqlsize fixed binary(15); dcl Sqldaptr pointer;

/* Pointer to Null indicator*/

/* Variable Name */

/* number of sqlvars (sqln) */

Figure 2. The PL/I declaration of an SQL descriptor area

Embedding SQL statements

The first statement of your PL/I program must be a PROCEDURE or a PACKAGE statement. You can add SQL statements to your program wherever executable statements can appear. Each SQL statement must begin with EXEC (or EXECUTE)

SQL and end with a semicolon (;).

For example, an UPDATE statement might be coded as follows: exec sql update Department export Mgrno = :Mgr_Num where Deptno = :Int_Dept;

Comments

In addition to SQL statements, PL/I comments can be included in embedded SQL statements wherever a blank is allowed.

SQL style comments ('--') are supported when embedded in SQL statements.

Continuation for SQL statements

The line continuation rules for SQL statements are the same as those for other PL/I statements.

Including code

SQL statements or PL/I host variable declaration statements can be included by placing the following SQL statement at the point in the source code where the statements are to be embedded: exec sql include member;

Margins

SQL statements must be coded in columns

m

through

n

where

m

and

n

are specified in the MARGINS(

m

,

n

) compile-time option.

Names

Any valid PL/I variable name can be used for a host variable and is subject to the following restriction: Do not use host variable names, external entry names, or access plan names that begin with 'SQL', 'DSN', or 'IBM'. These names are reserved

160

PL/I for Windows Programming Guide

SQL preprocessor

for the database manager or PL/I. The length of a host variable name must not exceed 100 characters.

Statement labels

With the exception of the END DECLARE SECTION statement, and the INCLUDE text-file-name statement, executable SQL statements, like PL/I statements, can have a label prefix.

WHENEVER statement

The target for the GOTO clause in an SQL WHENEVER statement must be a label in the PL/I source code and must be within the scope of any SQL statements affected by the WHENEVER statement.

Using host variables

All host variables used in SQL statements must be explicitly declared, and all host variables within an SQL statement must be preceded by a colon (:).

Subscripts must not be used in host variable references.

The following topics describe the details of using host variables: v

“Using arrays as host variables”

v

“Declaring host variables”

Using arrays as host variables:

You can use an array as a host variable only when it is an array of indicator variables for a host structure. That array must be one-dimensional, have the

CONNECTED attribute, and have constant bounds.

All other use of arrays as host variables is invalid.

Declaring host variables:

Host variable declarations can be made at the same place as regular PL/I variable declarations.

Only a subset of valid PL/I declarations are recognized as valid host variable declarations. The preprocessor does not use the data attribute defaults specified in the PL/I DEFAULT statement. The preprocessor ignores the DEFINE ALIAS and

DEFINE STRUCT statements, so variables with attributes that are dependent on them may not be used as host variables. If the declaration for a variable is not recognized, any statement that references the variable might result in the message:

’The host variable token ID is not valid’

To use a structure that is declared with LIKE or an element of this structure as a host variable, the declaration for the LIKE object must be visible to the SQL preprocessor. For example, the LIKE object must not be in a %INCLUDE file that has not been included.

You can use restricted expressions in host variable declarations to define the bounds of an array or the length of a string as long as the expression has one of the following forms:

Chapter 4. PL/I preprocessors

161

SQL preprocessor

v

A prefix operator applied to an expression where the expression can be collapsed to an integer v

An add or sub operator applied to two expressions where both expressions can be collapsed to integers v

A multiply operator applied to two expressions where both expressions can be collapsed to integers v

A reference to a named constant where the reference can be collapsed to an integer v One of these built-in functions: INDICATORS, HBOUND, LENGTH, and

MAXLENGTH v

A number that is an integer

Only the names and data attributes of the variables are used by the preprocessor; the alignment, scope, and storage attributes are ignored.

Declaring scalar host variables:

You must declare a scalar host variable with one of the following data attributes:

CHARACTER, GRAPHIC, or WIDECHAR

Host variables that are declared with the CHARACTER, GRAPHIC, or

WIDECHAR attributes are called string host variables. The following restrictions apply to the string host variable: v

It must have either the NONVARYING or VARYING attribute.

v

If it has the VARYING attribute, it must have the NATIVE attribute.

FIXED BINARY, FIXED DECIMAL, or FLOAT

Host variables that are declared with the FIXED and BINARY, FIXED and

DECIMAL, or FLOAT attributes are called numeric host variables. The following restrictions apply to the numeric host variable: v

It must have the REAL attribute.

v If it has the FIXED and BINARY attributes, it must have the SIGNED and NATIVE attributes, a zero scale factor, and a precision greater than

7.

v

If it has the FIXED and DECIMAL attributes, it must have a non-negative scale factor that is smaller than its precision.

v

If it has the FLOAT and DECIMAL attributes, it must have a precision that is less than 17.

v

If it has the FLOAT and BINARY attributes, it must have a precision that is less than 54.

SQL TYPE

Host variables that are declared with the SQL TYPE attribute are called

SQL TYPE host variables. The attribute specification must conform to one of the following syntax diagrams:

BINARY

SQL TYPE IS BINARY (

length

)

VARBINARY

SQL TYPE IS VARBINARY (

length

)

162

PL/I for Windows Programming Guide

SQL preprocessor

Result set locator

SQL TYPE IS RESULT_SET_LOCATOR

ROWID

SQL TYPE IS ROWID

Table locator

SQL TYPE IS TABLE LIKE

table-name

AS LOCATOR

LOB file reference

SQL TYPE IS BLOB_FILE

CLOB_FILE

DBCLOB_FILE

LOB locator

SQL TYPE IS BLOB_LOCATOR

CLOB_LOCATOR

DBCLOB_LOCATOR

LOB variable

SQL TYPE IS BLOB

CLOB

DBCLOB

(

length

K

M

G

)

BLOB

You can also use

BINARY LARGE OBJECT

as an alternative for

BLOB

.

CLOB

You can also use either

CHARACTER LARGE OBJECT

or

CHAR LARGE OBJECT

as an alternative for

CLOB

.

XML LOB variable

) SQL TYPE IS XML AS BLOB

CLOB

DBCLOB

(

length

K

M

G

BLOB

You can also use

BINARY LARGE OBJECT

as an alternative for

BLOB

.

CLOB

You can also use either

CHARACTER LARGE OBJECT

or

CHAR LARGE OBJECT

as an alternative for

CLOB

.

XML file reference

Chapter 4. PL/I preprocessors

163

SQL preprocessor

SQL TYPE IS XML AS BLOB_FILE

CLOB_FILE

DBCLOB_FILE

The following constant declarations are generated by the SQL preprocessor.

You can use them to set the file option variable when you use the file reference host variables:

DCL SQL_FILE_READ

DCL SQL_FILE_CREATE

FIXED BIN(31) VALUE(2);

FIXED BIN(31) VALUE(8);

DCL SQL_FILE_OVERWRITE FIXED BIN(31) VALUE(16);

DCL SQL_FILE_APPEND FIXED BIN(31) VALUE(32);

Determining equivalent SQL and PL/I data types

The base SQLTYPE and SQLLEN of host variables are determined according to the following table. If a host variable appears with an indicator variable, the SQLTYPE is the base SQLTYPE plus one.

Table 3. SQL data types generated from PL/I declarations

4000

PL/I Data Type

BIN FIXED(n), n < 16

BIN FIXED(n), n ranges from 16 to 31

DEC FIXED(p,s)

SQLTYPE of

Host Variable

500

496

484

BIN FLOAT(p), 22

≤ p

≤

53 480

DEC FLOAT(m), 7

≤ m

≤

16 480

CHAR(n), 1

≤ n

≤

254

CHAR(n) VARYING, 1

≤ n

≤

CHAR(n) VARYING, n >

4000

GRAPHIC(n), 1

≤ n

≤

127

GRAPHIC(n) VARYING, 1

≤ n

≤

2000

GRAPHIC(n) VARYING, n >

2000

452

448

456

468

464

472

SQLLEN of

Host Variable

2

4 n n

8

8 p (byte 1) s

(byte 2) n n n n

SQL Data Type

SMALLINT

INTEGER

DECIMAL(p,s)

FLOAT

FLOAT

CHAR(n)

VARCHAR(n)

LONG VARCHAR

GRAPHIC(n)

VARGRAPHIC(n)

LONG VARGRAPHIC

Since SQL does not have single or extended precision floating-point data type, if a single or extended precision floating-point host variable is used to insert data, it is converted to a double precision floating-point temporary and the value in the temporary is inserted into the database. If the single or extended precision floating-point host variable is used to retrieve data, a double precision floating-point temporary is used to retrieve data from the database and the result in the temporary variable is assigned to the host variable.

The following table can be used to determine the PL/I data type that is equivalent to a given SQL data type.

Table 4. SQL data types mapped to PL/I declarations

SQL Data Type

SMALLINT

PL/I Equivalent

BIN FIXED(15)

Notes

164

PL/I for Windows Programming Guide

SQL preprocessor

Table 4. SQL data types mapped to PL/I declarations (continued)

SQL Data Type PL/I Equivalent Notes

INTEGER

DECIMAL(p,s)

FLOAT

CHAR(n)

VARCHAR(n)

LONG VARCHAR

GRAPHIC(n)

VARGRAPHIC(n)

BIN FIXED(31)

DEC FIXED(p) or

DEC FIXED(p,s)

BIN FLOAT(p) or

DEC FLOAT(m)

CHAR(n)

CHAR(n) VAR

CHAR(n) VAR

GRAPHIC(n)

GRAPHIC(n) VAR

LONG VARGRAPHIC GRAPHIC(n) VAR

DATE

TIME

TIMESTAMP

CHAR(n)

CHAR(n)

CHAR(n) p = precision and s = scale; 1

≤

22

1

1 s

≤

≤

≤

≤ n n p p

≤

≤

≤ 53 7

254

4000 n > 4000

≤ m ≤ 16

≤ p

≤

31 and 0

n

is a positive integer from 1 to 127 that refers to the number of double-byte characters, not to the number of bytes

n

is a positive integer that refers to the number of double-byte characters, not to the number of bytes; 1 ≤ n ≤ 2000 n > 2000

n

must be at least 10

n

must be at least 8

n

must be at least 26

Determining compatibility of SQL and PL/I data types

PL/I host variables in SQL statements must be type compatible with the columns which use them: v

Numeric data types are compatible with each other. A SMALLINT, INTEGER,

DECIMAL, or FLOAT column is compatible with a PL/I host variable of BIN

FIXED(15), BIN FIXED(31), DECIMAL(

p

,

s

), BIN FLOAT(

n

) where

n

is from 22 to

53, or DEC FLOAT(

m

) where

m

is from 7 to 16.

v

Character data types are compatible with each other. A CHAR or VARCHAR column is compatible with a fixed-length or varying-length PL/I character host variable.

Graphic data types are compatible with each other. A GRAPHIC or

VARGRAPHIC column is compatible with a fixed-length or varying-length PL/I graphic character host variable.

v

Datetime data types are compatible with character host variables. A DATE,

TIME, or TIMESTAMP column is compatible with a fixed-length or varying-length PL/I character host variable.

When necessary, the Database Manager automatically converts a fixed-length character string to a varying-length string or a varying-length string to a fixed-length character string.

Using host structures

A PL/I host structure name can be a structure name with members that are not structures or unions. For example: dcl 1 A,

2 B,

3 C1 char(...),

3 C2 char(...);

Chapter 4. PL/I preprocessors

165

SQL preprocessor

In this example, B is the name of a host structure consisting of the scalars C1 and

C2.

Host structures are limited to two levels. A host structure can be thought of as a named collection of host variables.

Each leaf element of a host structure must have one of the following valid host

data attributes as discussed in “Declaring host variables” on page 161:

v

CHARACTER, GRAPHIC, or WIDECHAR v FIXED BIN, FIXED DEC, or FLOAT v

SQL TYPE

Using indicator variables

An indicator variable is a 2-byte integer (BIN FIXED(15)). On retrieval, an indicator variable is used to show whether its associated host variable has been assigned a null value. On assignment to a column, a negative indicator variable is used to indicate that a null value should be assigned.

Indicator variables are declared in the same way as host variables and the declarations of the two can be mixed in any way that seems appropriate to the programmer.

The SQL Preprocessor does not require that indicator arrays have a lower bound of one.

An indicator variable must have the attribute REAL NATIVE SIGNED FIXED

BIN(15).

Given the statement: exec sql

fetch

Cls_Cursor

into

:Cls_Cd,

:Day :Day_Ind,

:Bgn :Bgn_Ind,

:End :End_Ind;

Variables can be declared as follows: exec sql

begin declare section

; dcl Cls_Cd char(7); dcl Day dcl Bgn bin fixed(15); char(8); dcl End char(8); dcl (Day_Ind, Bgn_Ind, End_Ind) bin fixed(15); exec sql

end declare section

;

Host structure example

The following example shows the declaration of a host structure and an indicator array followed by an SQL statements that could be used to retrieve the data into the host structure.

dcl 1 games,

5 sunday,

10 opponents char(30),

10 gtime char(10),

10 tv char(6),

10 comments char(120) var; dcl indicator(4) fixed bin (15); exec sql fetch cursor_a into :games.sunday:indicator;

166

PL/I for Windows Programming Guide

SQL preprocessor

Using statements and compile-time options

This topic describes the way the preprocessor handles statements and compile-time options with SQL statements.

CONNECT TO statement:

You can use a host variable to represent the database name you want your application to connect to, for example: exec sql connect to :dbase;

If a host variable is specified: v

It must be a character or a character varying variable.

v

It must be preceded by a colon and must not be followed by an indicator variable.

v

The server-name that is contained within the host variable must be left-justified.

v

If the length of the server name is less than the length of the fixed-length character host variable, it must be padded on the right with blanks.

dcl dbase char (10); dbase = ’SAMPLE’; exec sql connect to :dbase;

/* blanks are padded automatically */ v

If a varying character host variable is used, you may receive the following warning from the compiler. You can ignore this message.

IBM1214I W xxx.x

A dummy argument is created for argument number 6 in entry reference SQLESTRD_API

DECLARE TABLE statement:

The preprocessor ignores all DECLARE TABLE statements.

DECLARE STATEMENT statement:

The preprocessor ignores all DECLARE STATEMENT statements.

Large Object (LOB) support

Binary Large Objects (BLOBs), Character Large Objects (CLOBs), and Double Byte

Character Large Objects (DBCLOBs), along with the concepts of LOB LOCATORS and LOB FILES are recognized by the preprocessor. See the DB2 manuals for more information on these subjects.

LOBS, CLOBS, and BLOBS can be as large as 2,147,483,640 bytes long (2 Gigabytes

- 8 bytes for PL/I overhead). Double Byte CLOBS can be 1,073,741,820 characters long (1 Gigabyte - 4 characters for PL/I overhead).

Note:

Under CMPAT(V1), the size of a BLOB, CLOB, or DBCLOB must not exceed

32767 KB.

Sample programs for LOB support

Three sample programs are provided to show how LOB types can be used in PL/I programs:

SQLLOB1.PLI

Shows how to fetch a BLOB from the database into a file.

Chapter 4. PL/I preprocessors

167

SQL preprocessor

SQLLOB2A.PLI

Shows how to use LOCATOR variables to modify a LOB without any movement of bytes until the final assignment of the LOB expression.

SQLLOB2B.PLI

Fetches the CLOB created in SQLLOB2A.PLI into a file for viewing.

User defined functions sample programs

You must install the following items to access the User Defined Function (UDF) sample programs: v DB2 V2.1 or later v

Sample database

Several PL/I programs have been included to show how to code and use UDFs.

Here is a short description of how to use them.

The file

UDFDLL.PLI

contains five sample UDFs. While these are simple in nature, they show basic concepts of UDFs.

MyAdd

Adds two integers and returns the result in a third integer.

MyDiv

Divides two integers and returns the result in a third integer.

MyUpper

Changes all lowercase occurrences of a,e,i,o,u to uppercase.

MyCount

Simple implementation of counter function using a scratchpad.

ClobUpper

Changes all lowercase occurrences of a,e,i,o,u in a CLOB to uppercase then writes them out to a file.

Use the command file bldudfdll to compile and link it into the udfdll library.

After the udfdll library has been compiled and linked, copy it to the user defined function directory for your database instance.

Before the functions can be used they must be defined to DB2. This is done using the CREATE FUNCTION command. The sample program, addudf.pli

, has been provided to perform the CREATE FUNCTION calls for each UDF. CREATE

FUNCTION calls would look something like the following:

CREATE FUNCTION MyAdd ( INT, INT ) RETURNS INT NO SQL

LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER

STYLE DB2SQL EXTERNAL NAME ’udfdll!MyAdd’

CREATE FUNCTION MyDiv ( INT, INT ) RETURNS INT NO SQL

LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER

STYLE DB2SQL EXTERNAL NAME ’udfdll!MyDiv’

CREATE FUNCTION MyUpper ( VARCHAR(61) ) RETURNS VARCHAR(61) NO SQL

LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER

STYLE DB2SQL EXTERNAL NAME ’udfdll!MyUpper’

CREATE FUNCTION MyCount ( ) RETURNS INT NO SQL

LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER

STYLE DB2SQL EXTERNAL NAME ’udfdll!MyCount’

SCRATCHPAD

168

PL/I for Windows Programming Guide

SQL preprocessor

CREATE FUNCTION ClobUpper ( CLOB(5K) ) RETURNS CLOB(5K) NO SQL

LANGUAGE C FENCED VARIANT NO EXTERNAL ACTION PARAMETER

STYLE DB2SQL EXTERNAL NAME ’udfdll!ClobUpper’

These are just sample CREATE FUNCTION commands. Consult your DB2 manuals for more information or refinement.

Use the command file bldaddudf to compile and link the addudf.pli

program.

After it is compiled and linked, run it to define the user defined functions to your database.

Several sample PL/I programs are provided that call the user defined functions you have just created and added to the database:

UDFMYADD.PLI

Fetches

ID and

Dept from the STAFF table then adds them together by calling

MyAdd

UDF. Use the command file bldmyadd to compile and link it.

UDFMYDIV.PLI

Fetches

ID and

Dept from the STAFF table then divides them by calling

MyDiv

UDF. Use the command file bldmydiv to compile and link it.

UDFMYUP.PLI

Fetches Name from the STAFF table then calls MyUpper to change the vowels to uppercase. Use the command file bldmyup to compile and link it.

UDFMYCNT.PLI

Fetches

ID from the STAFF table, outputs the count of the call, then divides

ID by the count. Use the command file bldmycnt to compile and link it.

UDFCLOB.PLI

Fetches the resume for employee '000150' then calls

ClobUpper to change the vowels to uppercase. Use the command file bldclobu to compile and link it. After this program is run, look in the file udfclob.txt

for the results.

Once these sample programs are compiled, linked, and the UDFs defined to DB2, the PL/I programs can be run from the command line.

These UDFs may also be called from the DB2 Command Line just line any other builtin DB2 function. For further information on how to customize and get the most out of your UDFs, please refer to your DB2 manuals.

Handling SQL error return codes

PL/I provides a sample program

DSNTIAR.PLI

that you can use to translate an

SQLCODE into a multi-line message for display purposes. This PL/I program provides the same function as the DSNTIAR program on mainframe DB2*.

You must compile DSNTIAR with the same DEFAULT and SYSTEM compile time options that are used to compile the programs that use DSNTIAR.

You must compile DSNTIAR with the following compiler options: v

DEFAULT(ASCII NATIVE LINKAGE(OPTLINK)) v

SYSTEM(WINDOWS)

The caller must declare the entry and conform to the interface as described in the mainframe DB2 publications. For your information, the declaration is of the following form:

Chapter 4. PL/I preprocessors

169

SQL preprocessor

dcl dsntiar entry options(asm inter retcode);

Three arguments are always passed:

arg 1

This input argument must be the SQLCA.

arg 2

This input/output argument is a structure of the form: dcl 1 Message,

2 Buffer_length fixed bin(15) init(

n

), /* input */

2 User_buffer char(

n

); /* output */

You must fill in the appropriate value for

n

.

arg 3

This input argument is a FIXED BIN(31) value that specifies logical record length.

SQL compatibility and migration considerations

The workstation compilers tolerate the following statement:

’ EXEC SQL CONNECT :userid IDENTIFIED BY :passwd’

The preceding statement is translated by the PL/I SQL preprocessor and sent to the database precompiler services as:

’ EXEC SQL CONNECT’

The allows VM SQL/DS users to compile their programs without making significant changes.

CICS support

If you do not specify the PP(CICS) option, EXEC CICS statements are parsed and variable references in them are validated. If they are correct, no messages are issued as long as the NOCOMPILE option is in effect. Without invoking the CICS preprocessor, real code cannot be generated.

You can use EXEC CICS statements in PL/I applications that run as transactions under CICS.

You can develop these applications under CICS on Windows for eventual execution under CICS that particular development platform or under CICS/ESA,

CICS/MVS, or CICS/VSE systems on S/390.

Make sure that the CICS installation adds all the

\OPT\...

settings to your system environment variables for Windows support. It is not necessary that the CICS system be operational when you are compiling your programs.

Programming and compilation considerations

When you are developing programs for execution under CICS, v

You must use the SYSTEM(CICS) compile-time option.

v

The MACRO option must follow the CICS option of PP.

170

PL/I for Windows Programming Guide

CICS support

If your CICS programs include files or use macros that contain EXEC CICS statements, you must also use either the MACRO compile-time option or the

MACRO option of PP before the CICS option of the PP option as shown in the following example: pp (macro(...) cics(...) macro(...) )

Make sure that INC is specified as an extension on the INCLUDE(EXT)

compile-time option, see “INCLUDE” on page 66.

The IBM.SYSLIB or INCLUDE environment variable must specify the CICS include file directories, for example: set include=d:\cicsnnn\plihdr;

The PL/I declarations generated by the CICSMAP, the Basic Mapping Support

(BMS) utility, are placed in the first directory specified in the INCLUDE

environment variable. For more information, see “Setting compile-time environment variables” on page 21.

Output produced in one of the following ways is written to the CPLI transient data queue (TDQ): v

PUT statements to SYSPRINT v

Messages written to the MSGFILE v

DISPLAY statements

Output produced by PLIDUMP is always written to the CPLD transient data queue.

The full workstation CICS API is supported for PL/I programs. Support is also provided for PL/I progams to use: v

External Presentation Interface (EPI) v

External Call Interface (ECI) v

External Transaction Initiation (ETI)

Other PL/I considerations that apply on S/390 CICS apply to CICS on the workstation also. The program behaves as though the STAE option is always in effect. The NOSTAE option is not supported.

If you are developing applications for eventual execution on S/390 CICS subsystems, you can check your PL/I programs for reentrancy violations with the

DEFAULT(NONASSIGNABLE) compile-time option.

For compatibility with CICS/ESA, CICS/MVS, and CICS/VSE, make sure that the

EXEC CICS commands are in upper case.

You can use PL/I FETCH and RELEASE under CICS.

A CICS program must not have more than one procedure that has

OPTIONS(MAIN).

The EXEC CICS ADDRESS and other similar commands that return a pointer to a

CICS control block (such as the TWA COMMAREA, and ACEE) might return a

SYSNULL() pointer if the control block does not exist. (For example, '00000000'x not 'FF000000'x) Your programs must use the SYSNULL built-in function to test such pointers.

Chapter 4. PL/I preprocessors

171

CICS support

Each PL/I compilation unit processed by the CICS preprocessor generates the following: dcl IBMMCICS_ID char(n) static init(’cics-id-and-version’);

The name, version, and release level of the CICS system for which your program was compiled are indicated.

The CICS preprocessor requires the compiler option DEFAULT(ASCII NATIVE

IEEE) be in effect.

You must have CICS installed before you can compile a program containing EXEC

CICS statements. To find out how to install CICS on your workstation, refer to the installation instructions for that product.

CICS preprocessor options

The following syntax diagram show options supported by the CICS preprocessor.

PP ( CICS ( '

NOSOURCE

SOURCE

NOPRINT

PRINT

NODECK

DECK

EDF

NOEDF

DEBUG

NODEBUG

' ) )

Abbreviations: S, NS, D, ND

SOURCE or NOSOURCE

Specifies whether or not the source input to the CICS preprocessor is printed.

PRINT or NOPRINT

Specifies whether or not the source code generated by the CICS preprocessor is printed in the source listing(s) produced by subsequent preprocessors or the compiler.

DECK or NODECK

Specifies that the CICS preprocessor output source is written to a file with the extension .DEK. The file is in the current directory.

EDF or NOEDF

Specifies whether or not the CICS Execution Diagnostic Facility (EDF) is to be enabled for the PL/I program. There is no performance advantage in specifying NOEDF, but the option can be useful in preventing CICS commands from appearing on EDF displays in well tested programs.

DEBUG or NODEBUG

Specifies whether or not the CICS preprocessor is to pass source program line numbers to CICS for use by the CICS Execution Diagnostic Facility (EDF).

CICS preprocessor options environment variables

You can set the default options for the CICS preprocessor by using the

IBM.PPCICS environment variable. See “IBM.PPCICS” on page 22.

172

PL/I for Windows Programming Guide

CICS support

Coding CICS statements in PL/I applications

You can code CICS statements in your PL/I applications using the language defined in

TXseries for Multiplatforms, CICS Application Programming Guide

in

TXSeries for Multiplatforms Information Center at publib.boulder.ibm.com/ infocenter/txformp/v7r1/.

Specific requirements for your CICS code are described in the sections that follow.

Embedding CICS statements

The first statement of your PL/I program must be a PROCEDURE statement. You can add CICS statements to your program wherever executable statements can appear. Each CICS statement must begin with EXEC (or EXECUTE) CICS and end with a semicolon (;).

For example, the GETMAIN statement might be coded as follows: exec cics getmain set(blk_ptr) length(stg(blk));

Comments

In addition to the CICS statements, PL/I comments can be included in embedded

CICS statements wherever a blank is allowed.

Continuation for CICS statements

Line continuation rules for CICS statements are the same as those for other PL/I statements.

Including code

If included code contains EXEC CICS statements or your program uses PL/I macros that generate EXEC CICS statements, you must use one of the following: v

The MACRO compile-time option v

The MACRO option of the PP option (before the CICS option of the PP option)

Margins

CICS statements must be coded within the columns specified in the MARGINS compile-time option.

Statement labels

EXEC CICS statements, like PL/I statements, can have a label prefix.

Writing CICS transactions in PL/I

This section describes the rules and guidelines that apply to PL/I support of CICS on the workstation.

You can use PL/I with CICS facilities to write application programs (transactions) for CICS subsystems. If you do this, CICS provides facilities to the PL/I program that would normally be provided directly by the operating system. These facilities include most data management facilities and all job and task management facilities.

You should observe the following rules to ensure compatibility with S/390 PL/I

CICS support.

Chapter 4. PL/I preprocessors

173

CICS support

v

Do not use macro level support, only command level support is provided.

v

Do not use any PL/I input or output except:

Stream output for SYSPRINT

PLIDUMP

Since these are intended for debugging purposes only, you should not include them in production programs for performance reasons.

v Do not use the following statements:

DELAY

WAIT v

Do not use the PLISRTx built-in subroutines.

v

Do not make calls to IMS using the PLITDLI, ASMTDLI, or EXEC DLI.

v

Do not communicate with FORTRAN, COBOL, or C, using PL/I interlanguage facilities. However, CICS programs written in different languages can communicate with each other using EXEC CICS LINK or XCTL commands.

Subroutines written in a language other than PL/I can be called using PL/I interlanguage facilities providing those subroutines do not contain any EXEC

CICS code. If you want to communicate with a non-PL/I program that contains

EXEC CICS code, you must use EXEC CICS LINK or EXEC CICS XCTL as stated.

CICS abends used for PL/I programs

APLS

This abend is issued on termination, if termination is caused by the ERROR condition, and the ERROR condition was not caused by an abend (other than an ASRA abend).

This is the abend code issued by PL/I when either:

1.

A transaction terminates in error due to a PL/I software interrupt

(CONVERSION, for example), and there is no ERROR ON-unit

2.

The program takes normal return from the ERROR ON-unit.

Because the program failed, the failure must be reflected to CICS on your workstation as an abend so that DTB, and so on, can occur if necessary.

APLT

An error was detected in the user exit.

CICS run-time user exit

It is strongly recommended that you review and modify (if necessary) the

IBM-supplied CICS user exit, CEEFXITA. See “Using the CICS run-time user exit” on page 375.

174

PL/I for Windows Programming Guide