Previous Topic: Connecting to a DictionaryNext Topic: Batch Processing


Using SET OPTIONS to Select Options

You can optionally include a SET OPTIONS statement in an IDMSBCF (batch) or OCF (online) session to do the following:

Syntax
                    ┌──────────────────────────────┐
►►─── SET OPTIONS ──▼─┬─ session-option ───────┬───┴───────cmd-delimiter───►◄
                      ├─ format-option ────────┤
                      ├─ io-option ────────────┤
                      └─ cmd-delimiter-option ─┘

Expansion of session-option

►►─┬─────────────────────────────────────────────┬───────────────────────────►◄
   └─┬─ AUTOCOMMIT ──┬─ ON ◄──┬────────────┬─┬─┬─┘
     │               │        └─ CONTINUE ─┘ │ │
     │               ├─ COMMAND ─────────────┤ │
     │               └─ OFF ─────────────────┘ │
     └─ ON ERROR ─┬─ END ────────┬─────────────┘
                  ├─ CONTINUE ◄──┤
                  └─ ROLLBACK ───┘

Expansion of format-option

►►──┬──────────────────────────────────────────────────────────────────────┬─►◄
    └─┬─ TITLE ─┬─ 'title' ─┬─────────────────────────────────────────────┬┘
      │         └─ DEFAULT ─┘                                             │
      ├─ HEADINGS ─┬─ OFF ──┬─────────────────────────────────────────────┤
      │            └─ ON ◄──┘                                             │
      ├─ LINES ─┬─ 60 ◄────────┬──────────────────────────────────────────┤
      │         └─ line-count ─┘                                          │
      ├─ WIDTH ─┬─ PAGE character-count ────────────────────────────────┬─┤
      │         ├─ CHARacter ─┬─ 80 ◄─────────────────────┬─────────────┤ │
      │         │             └─ maximum-character-count ─┘             │ │
      │         ├─ NUMeric maximum-character-count ─────────────────────┤ │
      │         └─ COLUMN ─┬─ column-number  maximum-character-count ─┬─┘ │
      │                    └─ OFF ────────────────────────────────────┘   │
      ├─ UNDERLINE underline-character ───────────────────────────────────┤
      ├─ PAGEBREAK ─┬─ column-number ─┬─────────────────────────────────┬─┤
      │             │                 └ column-number ┬────────────────┬┘ │
      │             │                                 └ column-number ─┘  │
      │             └─ OFF ───────────────────────────────────────────────┤
      ├─ STATUS ─┬─ OFF ───┬──────────────────────────────────────────────┤
      │          └─ ON ◄───┘                                              │
      ├─ COMPRESS ─┬─ ON ────┬────────────────────────────────────────────┤
      │            └─ OFF ◄──┘                                            │
      └─ COLUMN WRAP ─┬─ OFF ──┬──────────────────────────────────────────┘
                      └─ ON ◄──┘

Expansion of io-option

►►─┬── OUTPUT TO ────┬─── SYSLST ◄────────┬───────────────────────────┬─────►◄
   │                 └─ output-ddname ────┘                           │
   └── INPUT FROM ────┬─ SYSIPT ◄──────┬──────────────────────────────┘
                      └─ input-ddname ─┘

Expansion of cmd-delimiter-option

►►──── COMMAND DELIMITER ───┬──── DEFAULT ◄─────────────┬────────────────────►◄
                            └─── 'new-cmd-delimiter' ───┘
Parameters
cmd-delimiter

The current command delimiter to terminate the SET OPTIONS command. Initially the command delimiter is the semicolon(;) character, but it can be modified with the SET OPTIONS cmd-delimiter-option command

session-option

On a SET OPTIONS statement, specifies session control options such as when to commit and rollback work and whether to continue processing when a statement execution results in an error.

AUTOCOMMIT

Specifies AUTOCOMMIT options after successful statement execution (for more information about options for statements that return errors, see the ON ERROR parameter). AUTOCOMMIT options are shown in the following table.

Note: AUTOCOMMIT does not apply to utility statements.

Option

IDMSBCF

OCF

OCFX

AUTOCOMMIT

ON

(default)

Executes a COMMIT WORK RELEASE after the last statement in the input stream.

Executes a COMMIT WORK CONTINUE at the end of the edit buffer. Executes a COMMIT WORK RELEASE at the end of the SQL session; resources are released and temporary tables are dropped.

Executes a COMMIT WORK RELEASE at the end of the module.

AUTOCOMMIT

ON CONTINUE

N/A

Holds resources until a COMMIT is issued, enabling you to keep temporary tables; note that this option can slow performance and should be used with caution.

N/A

AUTOCOMMIT

COMMAND

Executes a COMMIT WORK CONTINUE after each successfully executed statement.

AUTOCOMMIT

OFF

No automatic COMMIT occurs; you must specify COMMIT WORK RELEASE manually.

IDMSBCF and OCFX—A release is issued at the end of processing, and this may cause a rollback if any work has not been committed.

ON ERROR

Specifies whether the session ends when a statement returns an error status code (a code with a value less than zero). Options are shown in the following table.

Note: ROLLBACK does not apply to utility statements.

Option

IDMSBCF

OCF

OCFX

ON ERROR

CONTINUE

(default)

Continues executing.

Continues executing.

Continues executing.

ON ERROR

END

Ends job step and session. Proceeds with the AUTOCOMMIT option.

Ends execution of commands in the current edit buffer and ends the SQL session. Does not end the OCF session. Proceeds with the AUTOCOMMIT option.

Ends execution of commands in the module and ends the session. Proceeds with the AUTOCOMMIT option.

ON ERROR

ROLLBACK

Issues a ROLLBACK RELEASE and ends job step.

Issues a ROLLBACK RELEASE and ends the SQL session. Does not end the OCF session.

Issues a ROLLBACK RELEASE and ends the execution of the module.

format-option

On a SET OPTIONS statement, specifies options for formatting the output of an SQL SELECT statement.

TITLE

Specifies a user-defined title line or resets the default title line. The TITLE parameter applies to IDMSBCF only.

'title'

Overrides the default title line with the specified title. You must enclose a title in single quotes.

DEFAULT

Resets the title line to the default. The default title line is 'IDMS Batch Command Facility'.

HEADINGS

Enables or suppresses page breaks and the output formatting that goes with them.

OFF

Suppresses page breaks. The title and column headings appear only once. Use this parameter when you intend to browse batch output online. OFF is the OCF default.

ON

Enables page breaks so that column name headings appear at the top of each page. ON is the IDMSBCF default.

LINES line-count

Sets the number of lines per page (the default is 60).

WIDTH

Sets page and/or column widths, or resets default widths.

PAGE character-count

Sets the width of a page for output. The range for IDMSBCF or OCFX is 40 to 132 (anything less than 40 is set to 40, anything greater than 132 is set to 132). The maximum value you should specify for OCF is 76; this reserves three characters for the *+ and space character preceding output; to suppress these characters, specify WIDTH PAGE 79.

Note: The PAGE parameter overrides the CHARACTER parameter.

CHARacter maximum-character-count

Sets the maximum width of non-numeric columns. Range is 1 to the width of the page (the default is 80). Columns longer than maximum-character-count are wrapped within the line. WIDTH CHAR must be less than the value specified for WIDTH PAGE.

NUMeric maximum-character-count

Sets the maximum width of numeric columns. Range is 1 to 32 (the default is the maximum length for the data type). If an exact value (including the sign) contains more digits than maximum-character-count, the value is replaced in output by a string of asterisks. Approximated values are rounded to fit the specified width of the column.

COLUMN column-number maximum-character-count

Sets the maximum width of the column identified by column-number. The maximum value you can specify for maximum-character-count is the width of the page. This parameter overrides WIDTH CHARACTER and WIDTH NUMERIC parameters for the specified column.

COLUMN OFF

Turns off all column width settings that were specified using the WIDTH COLUMN parameter.

UNDERLINE underline-character

Specifies the character that is to be used to underline column headings in output. The default is a blank space.

PAGEBREAK

Enables or disables settings required for a page break.

column-number

Specifies the number of an output column that is to be used to control page breaks. A change in the value of a column forces a page break. You can specify up to three column numbers. The HEADING OFF and COLUMN WRAP ON parameters disable this parameter.

OFF

Clears the column settings specified in the PAGEBREAK parameter of a previous SET OPTIONS statement.

STATUS

Controls the display of return codes.

OFF

Specifies that only non-zero status codes are to be displayed after statement execution.

ON

Specifies that return codes are to be displayed after the execution of every statement. ON is the default.

COMPRESS

Controls truncation of the output resulting from the execution of an SQL SELECT statement.

ON

Specifies truncation of output columns so that an entire row fits on one line.

OFF

Specifies normal output without any truncation of lines. OFF is the default.

COLUMN WRAP

Enables or disables line wrap for output columns.

OFF

Specifies that non-numeric columns that are longer than the available output space are to be truncated.

ON

Specifies that non-numeric columns that are longer than the available output space are to be displayed on multiple lines. ON is the default unless the COMPRESS ON parameter is used.

io-option

On a SET OPTIONS statement, specifies options for controlling the input and output of the command facility. The io-option is for IDMSBCF (batch) only.

OUTPUT TO

Specifies where to write data output.

SYSLST

Writes data output to SYSLST. If the prior assignment of the OUTPUT stream was not SYSLST, the prior OUTPUT assignment is closed.

output-ddname

Specifies the z/OS DD name, z/VSE file name link name of a sequential data set to use for writing the data output.

When output is assigned to output-ddname, these rules apply:

  • WIDTH PAGE is automatically set to the record length (or maximum record length for variable record files) that was specified when the file associated with output-ddname was created. If no record length and record format were specified, the record format defaults to variable and the record length to block size - 4; if no block size was specified, a block size of 4096 is used.
  • HEADINGS are set to OFF.
  • The "non-data" information like the echoed command, eventual headers, the number of rows processed, and the SQL return code are output to SYSLST.
  • Output data are not prefixed by "*+".
  • Data are represented in string format, not in the native format. For example, a column defined as INT with value 12345678 is internally stored as a 4-byte binary value X'00BC614E'; in the output data however, the column value is 8-byte character string '12345678'.
  • The width of each column in the output file is determined by the larger value of the column width and the column header. For example, a column named "Date", defined as CHAR(10) uses 10 positions in the output file; a column named "MiddleInitial", defined as CHAR(1) uses 13 positions.
  • IDMSBCF inserts two blanks in between successive columns.
  • The output-ddname file is closed on the next SET OPTIONS OUTPUT or at program end.
INPUT FROM

Specifies where to read input.

SYSIPT

Reads input from SYSIPT.

input-ddname

Specifies the DD name of a sequential data set to use for reading commands.

When input is assigned to input-ddname, these rules apply:

  • Input from input-ddname can be any type and length supported by the operating system, that is, input is not limited to 80 character lines.
  • Columns 73 through 80 of the input are NOT considered as a line sequence number, that is, they should contain valid input data.
  • End-of-file on the input-ddname file automatically reassigns input to SYSIPT.
cmd-delimiter-option

On a SET OPTIONS statement, specifies the command facility terminator.

COMMAND DELIMITER

Specifies the character string whose value will be used to delimit command facility statements after the SET OPTIONS command has been executed.

new-cmd-delimiter

Specifies the character string literal to be used as a delimiter. 'Delimiter' must be a 1- to 32-character string.

DEFAULT

Specifies that the default of a semicolon (;) will be used as a delimiter.

Usage

Statement terminator

Use the command delimiter, by default a semicolon, to terminate a SET OPTIONS statement. The use of an alternate command delimiter is required when entering multi-statement SQL routine bodies using the CREATE PROCEDURE or CREATE FUNCTION SQL DDL commands. According to the SQL procedural language, multiple SQL statements must be separated by the semicolon. However, using the semicolon also as the command terminator would truncate the CREATE command after the first semicolon, and any statements thereafter would erroneously be interpreted as new commands for the command facility and not as statements that make up the rest of the SQL routine body.

Note: Specifying a command terminator string replaces the previous specified one or the default, the semicolon, if none was specified. The specification of a command delimiter, just as any SET OPTIONS parameter remains in effect until a new SET OPTIONS COMMAND DELIMITER is issued or until the end of the command facility session.

Number of SET OPTIONS statements in a job step

You can use more than one SET OPTIONS statement in an IDMSBCF or OCF session. This enables you to change session, formatting, io and command delimiter options without requiring you to end the session.

Each parameter you specify remains in effect to the end of the session unless you explicitly change that same parameter in a subsequent SET OPTIONS statement.

Page breaks for ordered information

You can use the PAGEBREAK parameter of SET OPTIONS to separate information sorted by the ORDER BY clause of the SQL SELECT statement.

Input and output assignment

You can use the OUTPUT TO parameter to output the resulting data of, for example, SQL commands to an intermediate file, which can then be used as input to IDMSBCF or a user written program.

Combining the OUTPUT TO and INPUT FROM parameters allow you to write IDMSBCF scripts to perform the following tasks:

Examples

Session control parameters

The following SET OPTIONS statement specifies that a COMMIT WORK CONTINUE is to be issued after the successful execution of each statement; ON ERROR END specifies that the session is to end if the execution of a statement results in an error.

set options autocommit command
        on error end;

Submitting batch and viewing online

The following example shows SET OPTIONS parameters that you might typically use to submit an IDMSBCF batch job and view the output online.

set options title 'employee list'
        headings on
        underline *
        lines 24
        width page 80
        width char 10
        width num 5
        width column 2 6
        pagebreak 2 4
        column wrap off;

With these parameters specified, the output is formatted as follows:

Effects of WIDTH PAGE and COMPRESS ON

The following example shows the output of a SELECT statement when the output exceeds the value specified by WIDTH PAGE. Because the screen is not wide enough to display all four columns of data, the data for the fourth column is displayed after all of the data for the first three columns is displayed.

OCF nn.n IDMS PAGE 1 LINE 1 1/137 cv SELECT EMP_LNAME,EMP_FNAME,D.DEPT_ID, DEPT_NAME FROM DEMOEMPL.DEPARTMENT D,DEMOEMPL.EMPLOYEE E WHERE D.DEPT_ID=E.DEPT_ID; *+ *+ EMP_LNAME EMP_FNAME DEPT_ID *+ --------- --------- ------- *+ Brooks John 3510 *+ Park Deborah 2210 *+ Smith Carl 3530 *+ Spade Samuel 4600 *+ Loren Martin 4600 *+ Anderson Alice 6200 *+ MacGregor Bruce 2200 *+ Lynn David 2200 *+ *+ DEPT_NAME *+ --------- *+ APPRAISAL - USED CARS *+ SALES - NEW CARS *+ APPRAISAL - SERVICE *+ MAINTENANCE *+ MAINTENANCE *+ CORPORATE ADMINISTRATION *+ SALES - USED CARS *+ SALES - USED CARS *+ 8 rows processed

As an alternative, you can specify COMPRESS ON. This truncates column output as needed so that all output can fit on a single line.

If you specify too many columns in the SELECT statement, COMPRESS ON may not work. In this case, an error message will alert you.

Effects of WIDTH CHARACTER and COLUMN WRAP OFF

The following example shows how output may be displayed when WIDTH CHARACTER is specified. The maximum width of non-numeric columns is set to 10. This causes the output for the 20-character JOB_TITLE column to wrap to subsequent output lines, as needed.

OCF nn.n IDMS NO ERRORS 1/59 cv SET OPTIONS WIDTH CHAR 10; *+ Status = 0 SELECT JOB_ID, JOB_TITLE, MIN_RATE, MAX_RATE, EFF_DATE FROM JOB; *+ *+ JOB_ID JOB_TITLE MIN_RATE MAX_RATE EFF_DATE *+ ------ --------- -------- -------- -------- *+ 4666 Sr Mechani 20500.00 45500.00 yyyy-mm-dd *+ c *+ 5555 Salesperso 15000.00 39500.00 yyyy-mm-dd *+ n *+ 4123 Recruiter 17500.00 28000.00 yyyy-mm-dd *+ *+ 4025 Writer - M 15500.00 25000.00 yyyy-mm-dd *+ ktng *+ 4023 Accountant 22000.00 60000.00 yyyy-mm-dd *+ *+ 8001 Vice Presi 45000.00 68000.00 yyyy-mm-dd *+ dent *+ 2077 Purch Cler 8500.00 15000.00 yyyy-mm-dd *+ k *+ 2051 AP Clerk 4.80 10.60 yyyy-mm-dd *+ . . .

Additional space for wrapping the 20 characters in JOB_TITLE is provided even when the column output does not require it. If you specify COLUMN WRAP OFF, the non-numeric columns will be truncated instead of wrapping.

Sample IDMSBCF script

The following IDMSBCF example is a fairly generic script to unload/load or copy a table or set of tables. The sample script allows null values; however, it does not allow data containing quotes, more exotic data types, such as GRAPHIC, VARGRAPHIC, BINARY, and so on.

Input Script

-------------------------------------------------------------------------
-- This scripts copies the rows from a source table to a target table.
-- It is assumed that the target table is already defined
-------------------------------------------------------------------------
--
-- Helper view to set the params of the Table copy
--
drop   view usera01.CopyTabParm;
create view usera01.CopyTabParm as
  select SCHEMA     as SrcSchema
       , Name       as SrcTable
       , 'USERA01'  as TgtSchema  -- Set value of TgtSchema
       , 'EMPLOYEE' as TgtTable   -- Set value of TgtTable
   from SYSTEM.TABLE
  where SCHEMA = 'DEMOEMPL'       -- Set value of SrcSchema
    and NAME   = 'EMPLOYEE'       -- Set value of SrcTable
;
--
-- Create the Unload syntax
--
set options OUTPUT to Unload;

select 'select ''insert into '
     || trim(TgtSchema) || '.' || trim(TgtTable)
     || ' VALUES( '''
     , '-'||'-', 0 as sequence
from usera01.CopyTabParm
union
SELECT
 '||''' || SUBSTR(', ', CAST(1/NUMBER as SMALLINT) + 1, 1)
 || '''||TRIM(VALUE('
 || SUBSTR('CAST(      ''''''''||     ''''''''||CAST('
         , (11 * (  LOCATE(TYPE, 'CHARACTER           ', 1)
                  + LOCATE(TYPE, 'VARCHAR             ', 1)
                  + LOCATE(TYPE, ' DATE               ', 1)) + 1)
         , 11)
 || trim(NAME) || ' '
 || SUBSTR(
    'as char(10))      ||''''''''            as char(10))||'''''''''
         , (18* (  LOCATE(TYPE, 'CHARACTER           ', 1)
                 + LOCATE(TYPE, 'VARCHAR             ', 1)
                 + LOCATE(TYPE, ' DATE               ', 1)) + 1)
         ,18)
 || ',''NULL''))'
  , '-'||'-', NUMBER as sequence
FROM SYSTEM.COLUMN, usera01.CopyTabParm
 WHERE TABLE  = SrcTable
   and schema = SrcSchema
union
select '||'');'' from '
     || trim(SrcSchema) || '.' || trim(SrcTable) || ';'
     , '-'||'-', 99999 as sequence
from usera01.CopyTabParm
order by sequence
;
--
-- Create the Load syntax for the new Table
--
set options OUTPUT to Load;
set options INPUT from Unload;

--
-- Load the new Table
--
set options OUTPUT to SYSLST;
set options INPUT from Load;

Output from Sample Generic Table Copy Script

Unload OUTPUT

select 'insert into USERA01.EMPLOYEE VALUES( ' -- 0
||' '||TRIM(VALUE(CAST(      EMP_ID as char(10))      ,'NULL'))           --  1
||','||TRIM(VALUE(CAST(      MANAGER_ID as char(10))      ,'NULL'))       --  2
||','||TRIM(VALUE(''''||     EMP_FNAME ||''''            ,'NULL'))        --  3
||','||TRIM(VALUE(''''||     EMP_LNAME ||''''            ,'NULL'))        --  4
||','||TRIM(VALUE(CAST(      DEPT_ID as char(10))      ,'NULL'))          --  5
||','||TRIM(VALUE(''''||     STREET ||''''            ,'NULL'))           --  6
||','||TRIM(VALUE(''''||     CITY ||''''            ,'NULL'))             --  7
||','||TRIM(VALUE(''''||     STATE ||''''            ,'NULL'))            --  8
||','||TRIM(VALUE(''''||     ZIP_CODE ||''''            ,'NULL'))         --  9
||','||TRIM(VALUE(''''||     PHONE ||''''            ,'NULL'))            --  10
||','||TRIM(VALUE(''''||     STATUS ||''''            ,'NULL'))           --  11
||','||TRIM(VALUE(CAST(      SS_NUMBER as char(10))      ,'NULL'))        --  12
||','||TRIM(VALUE(''''||CAST(START_DATE as char(10))||'''','NULL'))       --  13
||','||TRIM(VALUE(''''||CAST(TERMINATION_DATE as char(10))||'''','NULL')) --  14
||','||TRIM(VALUE(''''||CAST(BIRTH_DATE as char(10))||'''','NULL'))       --  15
||');' from DEMOEMPL.EMPLOYEE; -- 99999

Load OUTPUT

insert into USERA01.EMPLOYEE VALUES(  2299,NULL,'Samuel
','Spade               ',4600,'47 London St
','Canton              ','MA','02020    ',NULL,'L',33892200,'1991-02-04',NULL,'1958-01-09');
insert into USERA01.EMPLOYEE VALUES(  3411,2894,'Catherine
','Williams            ',5200,'566 Lincoln St
','Boston              ','MA','02010    ',NULL,'A',83356561,'1993-09-30',NULL,'1967-10-28');
insert into USERA01.EMPLOYEE VALUES(  4773,3082,'Janice
','Dexter              ',3510,'399 Pine St
','Medford             ','MA','02432
','5083847566','A',89675632,'1997-06-14',NULL,'1969-11-19');

   ...
   ...
   ...

insert into USERA01.EMPLOYEE VALUES(  3118,3222,'Alan
','Wooding             ',4500,'196 School St
','Canton              ','MA','02020
','5083766984','A',98746783,'1992-11-18',NULL,'1969-05-17');
insert into USERA01.EMPLOYEE VALUES(  3769,2894,'Julie
','Donelson            ',3520,'14 Atwood Rd
','Grover              ','MA','02976
','5084850432','A',67783532,'1994-08-31',NULL,'1967-08-15');

Using an alternate command delimiter

The definition of the following SQL procedure requires the use of an alternate command delimiter to avoid a collision of the default, the semicolon, with the delimiter in the SQL procedural language.

set options command delimiter '++';
drop procedure PRODUCTION.PROCESS ++
commit++
create procedure PRODUCTION.PROCESS
 (PROC_TYPE integer,PROC_VALUE char(2_))
   external name DPROCESS language SQL
begin
  set PROC_TYPE = 12;
  set PROC_VALUE = 'High';
end
++
set options command delimiter DEFAULT ++