Work Flow Language (WFL) Programming Reference Manual WFL

86001047-506_Work_Flow_Language_Programming_Reference_7.0_Nov2001 86001047-506_Work_Flow_Language_Programming_Reference_7.0_Nov2001

WFL WFL

User Manual: WFL

Open the PDF directly: View PDF .
Page Count: 468 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Documentation Notes
Table of Contents
Section 1. WFL Capabilities
Section 2. Job Initiation
Section 3. Job Structure
Section 4. Declarations
Section 5. Task Initiation
Section 6. Statements
Section 7. Expressions
Section 8. Basic Constructs
Section 9. WFL Control Options
Appendix A. Sample WFL Jobs
Appendix B. Reserved Words, Predefined Words, and Keywords
Appendix C. Understanding Railroad Diagrams
Appendix D. Related Product Information
Index
Master Glossary

Unisys e-@ction

ClearPath Enterprise

Servers

Work Flow Language (WFL)

Programming Reference Manual

ClearPath MCP Release 7.0

Printed in USA

November 2001 8600 1047–506

Unisys e-@ction

ClearPath Enterprise

Servers

Work Flow Language (WFL)

Programming Reference Manual

UNISYS

û 2001 Unisys Corporation.

ClearPath MCP Release 7.0

Printed in USA

November 2001 8600 1047–506

NO WARRANTIES OF ANY NATURE ARE EXTENDED BY THIS DOCUMENT. Any product or related information

described herein is only furnished pursuant and subject to the terms and conditions of a duly executed agreement to

purchase or lease equipment or to license software. The only warranties made by Unisys, if any, with respect to the

products described in this document are set forth in such agreement. Unisys cannot accept any financial or other

responsibility that may be the result of your use of the information in this document or software material, including

direct, special, or consequential damages.

You should be very careful to ensure that the use of this information and/or software material complies with the laws,

rules, and regulations of the jurisdictions with respect to which it is used.

This document is not a contract and does not create any representations or warranties by Unisys. All applicable

representations, warranties and covenants are contained only in the applicable agreement signed by the parties.

The information contained herein is subject to change without notice. Revisions may be issued to advise of such

changes and/or additions.

Notice to Government End Users: This is commercial computer software or hardware documentation developed at

private expense. Use, reproduction, or disclosure by the Government is subject to the terms of Unisys standard

commercial license for the products, and where applicable, the restricted/limited rights provisions of the contract data

rights clauses.

Correspondence regarding this publication can be e-mailed to doc@unisys.com.

Unisys, ClearPath, and e-@ction are registered trademarks of Unisys Corporation in the United States and other

countries. All other brands and products referenced in this document are acknowledged to be the trademarks or

registered trademarks of their respective holders.

Unisys e-@ction

ClearPath Enterprise

Servers

Work Flow Language (WFL)

Programming Reference

Manual

ClearPath MCP Release

7.0

Unisys e-@ction

ClearPath

Enterprise

Servers

Work Flow

Language (WFL)

Programming

Reference

Manual

ClearPath MCP

Release 7.0

8600 1047–506 8600 1047–506

Bend here, peel upwards and apply to spine.

8600 1047–506 iii

Contents

Section 1. WFL Capabilities ................................................................1–1

About This Manual ................................................................................1–1

Overview of WFL ..................................................................................1–2

Task Initiation ........................................................................................1–3

Other Task Initiation Statements .........................................1–3

Task Specifications ..............................................................1–5

Data Specifications ..............................................................1–6

Flow of Control Statements.................................................1–7

Processing Data ................................................................... 1–7

Subroutine Control .............................................................................. 1–10

Task Control ........................................................................................1–13

File Handling........................................................................................1–16

File Management ................................................................................ 1–18

Communication ...................................................................................1–20

Job Format .......................................................................................... 1–22

Section 2. Job Initiation .....................................................................2–1

Overview ...............................................................................................2–1

Sources for Job Initiation....................................................................... 2–2

START and WFL Commands from CANDE

Sessions .......................................................................... 2–2

START Statements from Running WFL Jobs ......................2–5

Operator Display Terminals (ODTs) .....................................2–6

Menu-Assisted Resource Control (MARC) .......................... 2–7

Distributed Systems Services..............................................2–7

User Programs in Other Languages .................................... 2–9

Magnetic Tapes .................................................................2–10

Job Continuation after a Task Fails .....................................................2–11

Job Restart after a Halt/Load............................................................... 2–12

ON RESTART Statement ................................................... 2–15

Dummy Files......................................................................2–15

Section 3. Job Structure.....................................................................3–1

Overview ...............................................................................................3–1

Job Syntax............................................................................................. 3–1

Job Structure .......................................................................3–1

Contents

iv 8600 1047–506

Job Contents ....................................................................... 3–2

Job Format........................................................................... 3–2

AT Hostname....................................................................... 3–3

Job Title................................................................................................. 3–4

Job Parameter List................................................................................ 3–5

Job Disposition...................................................................................... 3–8

Job Attribute List................................................................................... 3–9

Resource-Limiting Attributes............................................. 3–10

CLASS Specification ........................................................................... 3–12

FETCH Specification ........................................................................... 3–13

STARTTIME Specification ................................................................... 3–14

Declaration List ................................................................................... 3–16

Statement List..................................................................................... 3–17

WFL Job Example............................................................................... 3–19

Section 4. Declarations...................................................................... 4–1

Overview............................................................................................... 4–1

Declaration Syntax ................................................................................ 4–1

Scope of Declarations.......................................................... 4–2

Variable Initialization............................................................. 4–2

Constant Identifiers............................................................................... 4–3

Boolean Variables.................................................................................. 4–4

Integer Variables ................................................................................... 4–5

Real Variables........................................................................................ 4–6

String Variables ..................................................................................... 4–7

File Variables ......................................................................................... 4–8

Task Variables ....................................................................................... 4–9

Subroutines ......................................................................................... 4–10

Subroutine Parameters...................................................... 4–11

Global Data Specifications .................................................................. 4–13

Section 5. Task Initiation................................................................... 5–1

Overview............................................................................................... 5–1

Task Initiation Statements .................................................................... 5–1

Task Equation........................................................................................ 5–3

Task Attributes...................................................................................... 5–4

Task Attribute Assignment ................................................................... 5–8

Complex Task Attribute Assignments ................................................ 5–11

ACCESSCODE Assignment............................................... 5–12

CORE Assignment............................................................. 5–13

CURRENTDIRECTORY Assignment.................................. 5–14

FAMILY Assignment ......................................................... 5–15

OPTION Assignment ......................................................... 5–17

PRINTDEFAULTS Assignment .......................................... 5–19

RESOURCE Assignment ................................................... 5–21

SUPPRESSWARNING Assignment ................................... 5–22

USERCODE Assignment ................................................... 5–23

Using Task Variables ........................................................................... 5–24

Assigning Task Attributes.................................................. 5–25

Contents

8600 1047–506 v

Reusing Task Variables ......................................................5–27

Interrogating Task Attributes .............................................5–29

Interrogating Task Status .................................................................... 5–30

File Attribute Inquiry............................................................................5–31

Interrogating Complex Task Attributes ...............................................5–31

MYJOB and MYSELF Predeclared Task Variables..............................5–32

File Equations ......................................................................................5–33

Causing the Task to Use a Different Input or Output

File .................................................................................5–34

Changing the Attributes of Files Used by the Task ...........5–35

Causing the Task to Read from a Data Specification.........5–35

How the Task Can Override WFL File Equations...............5–35

Resolving Repeated File Equations to the Same File ........5–36

Global File Assignment........................................................................5–37

Using Remote Files ............................................................................. 5–38

File Attribute Assignment....................................................................5–39

Device Kind Assignment ..................................................................... 5–40

Serial Number Assignment ................................................................. 5–41

Using File Attributes............................................................................5–42

Assigning File Attributes....................................................5–44

Interrogating File Attributes ...............................................5–45

Nonresident Files ...............................................................5–46

Library Equation................................................................................... 5–48

Overriding WFL Library Equations ..................................... 5–48

Resolving Repeated Library Equations to the Same

Library ............................................................................ 5–49

Database Equation ..............................................................................5–50

Local Data Specifications ....................................................................5–51

Section 6. Statements ........................................................................6–1

Overview ...............................................................................................6–1

WFL Statement Groupings....................................................................6–2

ABORT Statement................................................................................. 6–5

ACCESS Statement............................................................................... 6–6

ADD Statement ..................................................................................... 6–7

ALTER Statement..................................................................................6–8

Archive Subsystem .............................................................................6–17

ARCHIVE Backup Statement ............................................. 6–19

ARCHIVE Statement Options ............................................6–22

ARCHIVE Disk Volume.......................................................6–23

ARCHIVE Disk Volume Attribute List................................. 6–24

ARCHIVE Tape Volume......................................................6–25

ARCHIVE Tape Volume Attribute List................................6–26

ARCHIVE CD Volume......................................................... 6–34

ARCHIVE CD Volume Attribute List...................................6–35

ARCHIVE Task Equation List..............................................6–37

ARCHIVE MERGE Statement ............................................ 6–38

ARCHIVE PURGE Statement.............................................6–39

ARCHIVE RELEASE Statement .........................................6–40

ARCHIVE RESTORE Statement......................................... 6–41

Contents

vi 8600 1047–506

ARCHIVE ROLLOUT Statement........................................ 6–43

Assignment Statements ..................................................................... 6–46

BIND Statement.................................................................................. 6–48

CASE Statement ................................................................................. 6–49

CATALOG Statement.......................................................................... 6–50

CHANGE Statement ........................................................................... 6–52

COMPILE or BIND Statement ............................................................ 6–54

Naming the Object Code File ............................................ 6–55

Choosing a Compiler ......................................................... 6–55

Binding............................................................................... 6–56

Object Code File Disposition ............................................. 6–56

Task Variables.................................................................... 6–57

Compiler Task Equation List .............................................. 6–58

File, Library, and Database Equations and Task

Attributes....................................................................... 6–59

Local Data Specifications................................................... 6–60

Compound Statement......................................................................... 6–62

COPY or ADD Statement.................................................................... 6–63

Copying Files ..................................................................... 6–65

Library Maintenance .......................................................... 6–66

COPY Options.................................................................... 6–68

COPY Request................................................................... 6–74

Copying Files from Tape or CD-ROM................................ 6–95

COPY and ADD Statement Examples ............................. 6–105

COPY File Transfer Services............................................ 6–109

CREATE LIBMAINTDIR Statement................................................... 6–121

CRUNCH Statement ......................................................................... 6–124

DISPLAY Statement.......................................................................... 6–125

DO Statement ................................................................................... 6–126

GO Statement ................................................................................... 6–127

IF Statement ..................................................................................... 6–128

INITIALIZE Statement ....................................................................... 6–130

INSTRUCTION Statement................................................................. 6–131

LOCK Statement ............................................................................... 6–132

LOG Statement ................................................................................. 6–133

MKDIR Statement............................................................................. 6–134

MODIFY Statement .......................................................................... 6–135

MOVE Statement.............................................................................. 6–137

Null Statement .................................................................................. 6–140

ON Statement ................................................................................... 6–142

OPEN Statement............................................................................... 6–145

PASSWORD Statement.................................................................... 6–146

PB Statement.................................................................................... 6–147

PRINT Statement .............................................................................. 6–148

Printing Portions of a File................................................. 6–151

PROCESS Statement........................................................................ 6–153

PTD Statement.................................................................................. 6–155

PURGE Statement ............................................................................ 6–156

RELEASE Statement......................................................................... 6–157

REMOVE Statement ......................................................................... 6–158

REPLACE Statement ........................................................................ 6–160

RERUN Statement ............................................................................ 6–161

Contents

8600 1047–506 vii

RESTORE Statement ........................................................................6–162

Library Maintenance ........................................................6–164

RESTORE Statement Options ......................................... 6–165

RESTORE Tape and CD-ROM Attributes.........................6–166

RETURN Statement ..........................................................................6–169

REWIND Statement ..........................................................................6–170

RUN Statement ................................................................................. 6–171

SECURITY Statement........................................................................ 6–177

START Statement..............................................................................6–181

STOP Statement ...............................................................................6–185

Subroutine Invocation Statement...................................................... 6–186

UNWRAP Statement.........................................................................6–189

USER Statement ...............................................................................6–192

VOLUME Statement .........................................................................6–193

Tape Volume Security ...................................................... 6–199

VOLUME ADD Statement with Tape Security

Subsystem................................................................... 6–200

WAIT Statement................................................................................6–204

WHILE Statement .............................................................................6–207

WRAP Statement..............................................................................6–208

Section 7. Expressions........................................................................7–1

Overview ...............................................................................................7–1

Boolean Expressions ............................................................................. 7–2

Boolean Primary................................................................... 7–3

Integer Expressions...............................................................................7–9

Integer Primary ..................................................................7–10

Real Expressions ................................................................................. 7–13

Real Primary....................................................................... 7–14

String Expressions...............................................................................7–17

String Primary .................................................................... 7–18

Mnemonic Primaries ...........................................................................7–28

Constant Expressions.......................................................................... 7–29

Boolean Constant Expression............................................7–30

Integer Constant Expression.............................................. 7–31

Real Constant Expression..................................................7–32

String Constant Expression................................................7–33

Section 8. Basic Constructs................................................................8–1

Overview ...............................................................................................8–1

Invalid and Valid Characters...................................................................8–2

Valid Character Elements.....................................................8–2

Identifiers...............................................................................................8–3

Constants .............................................................................................. 8–4

Names ...................................................................................................8–6

File Names, Titles, and Directories .......................................................8–8

Using String Primaries......................................................................... 8–13

Restrictions on the Use of String Primaries....................... 8–13

Passing Parameters to a Task............................................ 8–14

Contents

viii 8600 1047–506

Copying Multiple Files ....................................................... 8–15

Section 9. WFL Control Options......................................................... 9–1

Overview............................................................................................... 9–1

ERRORLIMIT Option............................................................................. 9–2

INCLUDE Option................................................................................... 9–3

LIST Option ........................................................................................... 9–5

NEWSEGMENT Option......................................................................... 9–6

Appendix A. Sample WFL Jobs..............................................................A–1

Overview...............................................................................................A–1

Compiling a Program.............................................................................A–2

Initiating Other Jobs..............................................................................A–6

Updating Files .......................................................................................A–7

Appendix B. Reserved Words, Predefined Words, and Keywords.......... B–1

Overview...............................................................................................B–1

Reserved Words ...................................................................................B–2

Predefined Words .................................................................................B–2

Keywords ..............................................................................................B–4

Appendix C. Understanding Railroad Diagrams .................................... C–1

Railroad Diagram Concepts...................................................................C–1

Paths....................................................................................C–1

Constants and Variables ......................................................C–2

Constraints...........................................................................C–3

Following the Paths of a Railroad Diagram ...........................................C–6

Railroad Diagram Examples with Sample Input....................................C–7

Appendix D. Related Product Information.............................................D–1

Index ..............................................................................................1

8600 1047–506 ix

Tables

5–1. Task Attribute Groupings....................................................................................5–4

5–2. Expressions for Task Attribute Inquiry ............................................................. 5–29

5–3. File Attribute Types ..........................................................................................5–42

5–4. Expressions for File Attribute Inquiry ............................................................... 5–45

C–1. Elements of a Railroad Diagram.........................................................................C–2

Tables

x 8600 1047–506

8600 1047–506 1–1

Section 1

WFL Capabilities

Work Flow Language (WFL) is used for constructing jobs that compile or run programs.

WFL includes variables, expressions, and flow-of-control statements that offer the

programmer a wide range of capabilities with regard to task control.

About This Manual

This manual is a complete language reference for WFL users, whether they are

beginning users just learning WFL, or experienced users who need to check on the

details of a particular construct.

Purpose and Scope

Although this manual sometimes mentions specific task attributes or file attributes, it

does not describe these attributes in great detail. For detailed information regarding task

attributes, refer to the Task Attributes Programming Reference Manual. For detailed

information about file attributes, refer to the File Attributes Programming Reference

Manual.

This manual also mentions some specific system commands that are entered at an

operator display terminal (ODT). For detailed information about these commands, refer to

the System Commands Operations Reference Manual.

Audience and Prerequisites

The audience for this manual consists of programmers and operators who need to write

jobs that initiate and control tasks.

The user is assumed to have had prior experience with programming in a block-

structured language (for example, ALGOL, COBOL, RPG, or some other block-structured

language). However, there is no single programming language the user needs to know to

understand this manual. Additionally, the user is assumed to be familiar with ClearPath

MCP systems, at least to the extent of knowing how to create and edit files by using

CANDE or the Editor.

If you are not familiar with ClearPath MCP systems, you should first read the MCP/AS

System Administration Guide and the MCP/AS System Operations Guide. If you are not

familiar with the concepts of process initiation and process control, you should first read

the Task Attributes Programming Reference Manual. If you prefer to learn by example,

consider reading WFL Made Simple.

Overview of WFL

1–2 8600 1047–506

How to Use This Manual

This manual is intended primarily for reference, although a new user can learn a great

deal about WFL by reading the first five sections. Section 6, “Statements,” begins with a

functional grouping of the various WFL statements, and then presents descriptions of

the statements in alphabetical order for quick reference.

Railroad diagrams are used to illustrate WFL syntax. If you are not familiar with this type

of syntax notation, you should read Appendix C, “Understanding Railroad Diagrams.”

Some WFL constructs share a common syntax. In certain instances, these constructs

share the same railroad diagram. For example:

<mm>

<dd>

ÚêÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄ/2\Ä<digit>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

The syntax for many WFL constructs is rather complex. To show an appropriate level of

detail, most railroad diagrams use basic constructs that are explained elsewhere in the

manual. You can quickly locate the more detailed syntax for these subordinate constructs

using the index.

Overview of WFL

WFL is used for constructing jobs that compile or run programs. WFL is a true

programming language with its own compiler that either produces an object code file

used in running a job or executes a job interpretively. A WFL job is always recompiled

each time it is run.

WFL can initiate programs that are written in any of the languages accepted on A Series

systems. It is a high-level language with flow-of-control structures and subroutines

analogous to those found in ALGOL. However, WFL includes features related to task

control that would be difficult or impossible to duplicate in any of the other available

languages.

One advantage to initiating tasks through WFL instead of through CANDE or some other

means is that a WFL job is automatically restarted if it is interrupted by a halt/load. This

capability is discussed under “Job Restart after a Halt/Load” in Section 2.

WFL accepts jobs from a large variety of sources. With a few exceptions, identical jobs

can be presented to WFL from all of the available sources. Section 2, “Job Initiation,”

describes the different sources from which WFL will accept jobs.

WFL supports the MultiLingual System (MLS). All error or warning messages given by

the WFL compiler can be translated into another language with the Message Translation

Utility. For more information, refer to the MLS Guide and the MSGTRANS Operations

Guide.

Task Initiation

8600 1047–506 1–3

WFL and the MCP must be the same release level to function properly. If the release

levels are not the same, WFL waits on an AX condition before freezing. It is possible to

proceed with a mismatched WFL by entering AX OK, but unexpected results might

occur. To declare a WFLSupport library that is the same release level as the MCP, use

the System Library (SL) command. To terminate the waiting WFLSupport library, enter

AX DS or use the Unlock (LP-) command and the Discontinue (DS) command.

The following pages outline the various capabilities of WFL and present example WFL

jobs. While most of the WFL statements will be mentioned here, you should refer to

Section 6, “Statements,” for a more complete description of a particular statement.

Task Initiation

The two basic capabilities of WFL are compiling and running programs. The two WFL

statements that correspond to these capabilities are called:

• COMPILE

• RUN

Other Task Initiation Statements

The other WFL statements that initiate tasks include:

• COPY and ADD for copying files

• BIND for invoking the Binder

• PB for running the SYSTEM/BACKUP utility

• PTD for initiating peripheral testing routines

• LOG for running the LOGANALYZER utility

• START for initiating other WFL jobs from the current job

Tasks initiated by any of these statements are executed serially; that is, the job waits for

the task to complete before continuing on to the next statement. However, any task can

be made to run asynchronously by preceding the task initiation statement with the word

PROCESS. Asynchronous tasks run in parallel with the job.

The START statement normally causes the job to be compiled synchronously and

executed asynchronously. A PROCESS START causes both the compile and execution to

occur asynchronously with the job.

An asynchronous task can also be initiated by a subroutine invocation statement that

occurs within a PROCESS statement. A subroutine invocation statement normally does

not initiate a task.

Task Initiation

1–4 8600 1047–506

Example

The following example shows a simple form of the COMPILE and RUN statements:

?BEGIN JOB RUNPROG;

COMPILE (JONES)OBJECT/ALGOL/TEST WITH ALGOL LIBRARY;

COMPILER FILE CARD(TITLE=ALGOL/TEST ON MYPACK);

RUN (JONES)OBJECT/ALGOL/TEST;

?END JOB.

The COMPILE statement in this example specifies that the object code file titled

(JONES)OBJECT/ALGOL/TEST is to be saved. (Other variations in the COMPILE

statement can be used to specify whether the object code file is to be run immediately,

saved and run immediately, or whether the source file is to be compiled for syntax only.)

The line beginning COMPILER FILE CARD is a file equation that tells the ALGOL compiler

the name of the source file to use as input. The RUN statement causes the program to

execute. The file title specified in the RUN statement must be the title of the object code

file (not the source file) of the program.

Task Initiation

8600 1047–506 1–5

Task Specifications

The following types of specifications can be included in a task initiation statement:

• Task attribute assignments

• Library equations

• File equations

• Database equations

• Local data specifications

Many task attributes with very diverse functions are available through WFL. Some of

them can be used to access information about the task execution, such as accumulated

processor and I/O time. Other functions alter the way the program is run, such as

specifying the priority to be assigned to a task or the usercode a task is to run under.

The task attributes available through WFL are listed under “Task Attributes” in Section 5.

For a more detailed description, refer to the task attribute descriptions in the Task

Attributes Reference Manual.

File equations can be used to modify attributes of the files used by a program, or can

cause the program to use different files than it normally would have. For example, file

equations can cause the program to read input from a different source than is specified

in the program, and write output to a different destination than is specified in the

program. This feature of WFL eliminates the need for many time-consuming alterations

and recompilations of existing programs.

For more information, see “File Equations” and “Task Equation” in Section 5 for further

information. Individual file attributes are described in the File Attributes Reference

Manual.

Examples

In the following example, the task attribute PRIORITY specifies the priority to be

assigned to the task:

?BEGIN JOB COMP/DATA;

RUN (RAJA)OBJECT/COMP/DATA; % Run the desired program with

PRIORITY=50; % a priority of 50

?END JOB.

The following example uses a file equation:

?BEGIN JOB WFLTEST;

RUN (WALLY)OBJECT/ALGOL/TEST;

FILE TERMIN(TITLE=WFLIN,KIND=DISK); % Causes the program to

% read from the disk file

% WFLIN, instead of the

% file TERMIN

?END JOB.

Task Initiation

1–6 8600 1047–506

Data Specifications

Data specifications supply input to a program that expects input from a card reader file

during execution; that is, a file declared in the program as being of kind READER.

A data specification can also be used in place of any input file the program reads by

file-equating the title of the input file to the title of the data specification in the WFL job,

and by declaring the type of input file to READER.

Two kinds of data specifications are available:

• Local data specifications

• Global data specifications

A global data specification can be declared at the start of a job, and can be used by more

than one task.

Example

The following example illustrates a job that uses a global data specification:

?BEGIN JOB INTREF;

DATA INPUT % Begin global data specification

? % End global data specification

RUN (WENDY)OBJECT/INT/REF;

FILE TERMIN(TITLE=INPUT,KIND=READER); % Causes the program to

% read from the global

% data specification INPUT

% instead of the file

% TERMIN.

?END JOB.

Task Initiation

8600 1047–506 1–7

Flow of Control Statements

The WFL jobs in the examples presented thus far have been set up to execute

statements in sequential order. However, WFL also enables you to execute statements

conditionally or repeatedly by using flow-of-control statements. The flow-of-control

statements include:

• IF

• DO

• WHILE

• CASE

• GO

The IF statement executes a certain statement only if the value of a particular Boolean

expression is TRUE.

The DO statement and the WHILE statement are both used to cause repeated execution

of a statement or set of statements. Both statements evaluate a Boolean expression

before each repetition is initiated, to decide whether to do it again. The DO statement

differs from the WHILE statement in that it checks the Boolean expression at the end of

the loop instead of at the start; the statements included in the loop are therefore

guaranteed to execute at least once.

The CASE statement chooses one of several possible alternative actions, depending on

the value of the variable or case expression that follows the word CASE.

Whenever the syntax of a flow-of-control statement calls for a statement to be included,

that statement can be another flow-of-control statement. Therefore, flow-of-control

statements can be nested to form complex flow-of-control structures.

Processing Data

The use of conditional statements implies that the job is going to be processing some

data that can vary at run time. The following kinds of data can vary at run time:

• WFL jobs that are stored on disk and initiated by a START statement can have

parameter values passed to them.

• During the course of a WFL job, the job can inspect the values of task attributes

associated with tasks that were initiated in the job. Certain task attributes record task

history. The WFL job can then make decisions about what to do next based on the

history of the task that was initiated.

• The job can also inspect the values of file attributes or test whether a file with a

given title is resident, and then make decisions accordingly.

• The job can include ACCEPT functions that will prompt you to supply input at run

time and will cause the job to wait for your reply.

Task Initiation

1–8 8600 1047–506

Examples

The following WFL job illustrates a use of the IF statement:

?BEGIN JOB WFLTEST;

TASK COMPOK;

DISPLAY "COMPILING NOW";

COMPILE (SFL)OBJECT/SORT/PROC WITH ALGOL [COMPOK] LIBRARY;

COMPILER FILE CARD(TITLE=SORT/PROC ON MYPACK);

IF COMPOK IS COMPILEDOK THEN

BEGIN

DISPLAY "COMPILED SUCCESSFULLY";

DISPLAY "RUNNING SORT/PROC";

RUN (SFL)OBJECT/SORT/PROC;

END

ELSE

DISPLAY "COMPILE NOT SUCCESSFUL --- WILL NOT RUN";

?END JOB.

This example first compiles a program, then inspects a task variable named COMPOK to

see whether the compile was successful. If the compile was successful, the Boolean

expression COMPOK IS COMPILEDOK evaluates to TRUE. In this case, the program that

was compiled will be run. If the compile was not successful, then no attempt is made to

run the program.

The DISPLAY statements in this example display messages at the ODT (and also at the

CANDE terminal where the job was initiated).

The following example illustrates one use of the CASE statement:

?BEGIN JOB WFLTEST(STRING COMPTYPE);

CASE COMPTYPE OF

BEGIN

("SYNTAX"): COMPILE (MAINT)OBJECT/ORD WITH COBOL74 SYNTAX;

COMPILER FILE CARD(TITLE=ORD,KIND=DISK);

("GO"): COMPILE (MAINT)OBJECT/ORD WITH COBOL74 GO;

COMPILER FILE CARD(TITLE=ORD,KIND=DISK);

("LIBRARY"): COMPILE (MAINT)OBJECT/ORD WITH COBOL74 LIBRARY;

COMPILER FILE CARD(TITLE=ORD,KIND=DISK);

("LIBRARY-GO"): COMPILE (MAINT)OBJECT/ORD WITH COBOL74 LIBRARY GO ;

COMPILER FILE CARD(TITLE=ORD,KIND=DISK);

ELSE: DISPLAY "INCORRECT COMPILE TYPE ENTERED";

END;

?END JOB.

In this example, a WFL job has been constructed that enables a user to compile a

particular file in any of four possible ways according to the string parameter specified in

the START statement.

The following table lists four START statements, each with a different string parameter

specified and the results of each statement.

Task Initiation

8600 1047–506 1–9

Statement Result

START WFLTEST(“SYNTAX”) Compiles the file ORD to check for syntax errors,

but does not save the object code file.

START WFLTEST(“GO”) Compiles and runs the file ORD, but does not

save the object code file.

START WFLTEST(“LIBRARY”) Compiles the file ORD, and saves the object code

file as (MAINT)OBJECT/ORD.

START WFLTEST(“LIBRARY-GO”) Compiles the file ORD and runs the object code

file. The object code file is saved as

(MAINT)OBJECT/ORD.

The following is an example of the DO statement:

?BEGIN JOB WFLTEST(INTEGER REPS);

INTEGER INTREPS := 0;

DO BEGIN

RUN (WALLY)OBJECT/STOCK/PLAN;

INTREPS := INTREPS + 1;

END

UNTIL INTREPS = REPS;

?END JOB.

This job runs the program (WALLY)OBJECT/STOCK/PLAN the number of times specified

in the parameter of the START statement that initiated this job. For instance, START

WFLTEST(7) runs the program (WALLY)OBJECT/STOCK/PLAN seven times.

Subroutine Control

1–10 8600 1047–506

Subroutine Control

A WFL job can include any number of subroutines, and each subroutine can contain

further subroutine declarations within itself. In addition, a subroutine can contain

statements invoking itself, or other subroutines in the WFL job. (The rules concerning

which subroutines can be invoked from a given subroutine are discussed under “Scope

of Declarations” in Section 4.)

WFL enables an identifier to be associated with a statement or group of statements. This

can be accomplished by using the subroutine declaration. Once a subroutine has been

declared, it can be invoked in the WFL job by using the identifier associated with it. The

subroutine is a convenient shorthand for referring to a piece of code that the WFL job is

going to invoke repeatedly.

Examples

The WFL subroutines can be invoked with parameters that pass values to the

subroutines. Consider the following example:

?BEGIN JOB WFLCHART(REAL VALUE1, REAL VALUE2, REAL VALUE3);

SUBROUTINE RUNCHART(REAL RVAL VALUE); % Beginning of subroutine

BEGIN % declaration

RUN (PORT)CHART/COL/NAV(RVAL);

END RUNCHART; % End of subroutine

% declaration

% WFL job statements follow

DISPLAY "RUNNING WITH FIRST VALUE SUPPLIED";

RUNCHART(VALUE1);

DISPLAY "RUNNING WITH SECOND VALUE SUPPLIED";

RUNCHART(VALUE2);

DISPLAY "RUNNING WITH THIRD VALUE SUPPLIED";

RUNCHART(VALUE3);

?END JOB.

This job is initiated with a START statement that has three real numbers specified as

parameters. The job then calls on the subroutine RUNCHART three times, each time

supplying a different parameter value to the subroutine. This method saves code

repetition when a lengthy subroutine is called.

Subroutine Control

8600 1047–506 1–11

The following example is a subroutine that invokes itself:

?BEGIN JOB WFLINV(INTEGER VALUE1, INTEGER VALUE2);

SUBROUTINE DISPLAYONE;

DISPLAY "IT WORKED ALL RIGHT";

SUBROUTINE RUNINV(INTEGER IVAL1);

BEGIN

RUN (PARTS)OBJECT/OLD/INV(IVAL1);

STATION=MYSELF(SOURCESTATION);

DISPLAYONE;

IVAL1 := IVAL1 + 1;

IF IVAL1 LEQ VALUE2 THEN

RUNINV(IVAL1);

END;

RUNINV(VALUE1);

DISPLAYONE;

?END JOB.

This job accepts two integer values as parameters. The job uses the first job parameter

as a parameter in the RUN statement for the program OBJECT/OLD/INV. This program is

run several times, with an increase in the value of the parameter each time, until the

parameter equals the value of the second parameter that was supplied to the job.

This example shows several kinds of subroutine invocations that are available. The outer

block of the WFL job calls on the subroutines RUNINV and DISPLAYONE. The subroutine

RUNINV also calls on the subroutine DISPLAYONE, which was previously defined.

Further, the subroutine RUNINV calls on itself, so that it will continue repeating as long

as the expression in the IF statement evaluates to TRUE.

Subroutine Control

1–12 8600 1047–506

The following example illustrates the use of the RETURN statement as a means of

exiting a subroutine early:

?BEGIN JOB WFLTEST(INTEGER VALUE1);

TASK T;

SUBROUTINE RUNTEST(INTEGER IVAL1);

BEGIN

RUN (WALLY)OBJECT/TEST(IVAL1) [T];

IF T ISNT COMPLETEDOK THEN

RETURN;

IVAL1 := IVAL1 + 1;

IF IVAL1 LEQ 7 THEN

RUNTEST(IVAL1);

END;

RUNTEST(VALUE1);

?END JOB.

This example runs the program (WALLY)OBJECT/TEST repeatedly. However, if the task

variable T indicates the program did not run successfully, the RETURN statement is

invoked to cause the subroutine to be exited. The remaining statements in the

subroutine will then be bypassed, and control will pass back to the parent of the

subroutine (in this case, the outer block of the WFL job).

Task Control

8600 1047–506 1–13

Task Control

Several WFL statements are available to control the execution of a task. These

statements determine

• When a task is run

• When a task is terminated

• How a task responds to error conditions

• What usercode a task runs under

These statements are referred to broadly as task control statements.

Task Control Statements

Task control statements include the following:

• ABORT

• STOP

• WAIT

• ON

• USER

The ABORT and STOP statements are available for terminating a job or task prematurely.

The difference between the two statements is that the ABORT statement displays

messages indicating that the job or task was terminated abnormally, while the STOP

statement indicates a normal termination. Generally these statements are used as part of

an IF statement or CASE statement, so that the job or task is terminated only if the

specified conditions are met.

The WAIT statement suspends job execution until some specified condition is met. The

uses of the WAIT statement include the following:

• To cause the job to wait for an asynchronous task to complete, or to wait until the

asynchronous task achieves a specified state

• To cause the job to wait until a file becomes resident

• To cause the job to wait for an OK message from the user

Task Control

1–14 8600 1047–506

Examples

This example illustrates a use of the ABORT statement:

?BEGIN JOB WFLTEST;

TASK COMPOK;

COMPILE (WALLY)OBJECT/MENU/PLAN WITH PASCAL [COMPOK] LIBRARY;

COMPILER FILE CARD(TITLE=MENU/PLAN ON MUNCHPACK);

IF COMPOK IS COMPILEDOK THEN

RUN (WALLY)OBJECT/MENU/PLAN

ELSE

ABORT "UNSUCCESSFUL COMPILE";

?END JOB.

This job first attempts to compile the source file MENU/PLAN. If the compile was

successful, the job will run the object code file that was the result of the compilation. If

the compile was not successful, the job is terminated abnormally by the ABORT

statement and the message “UNSUCCESSFUL COMPILE” is displayed.

The following example illustrates a use of the WAIT statement:

?BEGIN JOB WFLTEST;

TASK TEST1, TEST2;

PROCESS RUN (WALLY)OBJECT/SORTIT [TEST1];

PROCESS RUN (WALLY)OBJECT/SORT2 [TEST2];

WAIT

UNTIL TEST1 IS COMPLETED AND TEST2 IS COMPLETED;

RUN (WALLY)OBJECT/COLLATE;

?END JOB.

In this example, two asynchronous tasks are started by PROCESS statements. A

DO-UNTIL loop follows, instructing the job to wait until both asynchronous tasks are

completed before continuing.

The USER statement provides another form of task control. This statement changes the

usercode the WFL job is running under to the specified usercode. The tasks initiated by

the WFL job will then inherit the new usercode, and its associated privileges.

Task Control

8600 1047–506 1–15

The following is an example of the USER statement in a job:

?BEGIN JOB RECEIVABLE;

RUN OBJECT/INTEREST;

USER=SCROOGE/CALC;

RUN OBJECT/PENALTIES;

RUN (CRATCHIT)OBJECT/CREDIT;

?END JOB.

In this example, the first RUN statement runs the program OBJECT/INTEREST under the

job’s original usercode, which was determined at the time of job initiation. The USER

statement then changes the job’s usercode to usercode SCROOGE, which has CALC as

its password. The remaining two programs that the job initiates are then run under

usercode SCROOGE, even though the object code file for the last one resides under

usercode CRATCHIT.

The usercode of the job can also be set by specifying the USERCODE task attribute as a

job attribute, and the usercode for an individual task can be set by specifying the

USERCODE for that task.

File Handling

1–16 8600 1047–506

File Handling

Although a WFL job cannot read from or write to files itself, it provides considerable

control over the files that programs initiated through WFL can read from or write to. The

main tool that provides this control is file equation, which is discussed under “Task

Initiation” earlier in this section. In addition, there are several statements available in

WFL that provide even more flexibility in file handling.

File Handling Statements

Files can be opened in WFL by using the OPEN statement. The file specified in this

statement is opened with the I/O capabilities specified in the NEWFILE attribute,

FILEUSE attribute, or other attributes of the file. If the NEWFILE attribute or the

FILEUSE attribute is not assigned, an attempt is made to open the specified file for both

input and output. Refer to the File Attributes Reference Manual for more information

about file attributes.

The following table lists five statements that close files in different ways.

Statement Result

CRUNCH Closes a file and returns the unused portion of the last row of the

file to the system. Once a file is crunched, it takes up less space,

but can no longer be expanded. This statement is used for disk files

only.

LOCK Closes the file and, except for disk or pack files, saves the unit the

file resides on so that it is inaccessible to the system.

PURGE Removes a file and frees the area it was occupying for reuse.

RELEASE Closes and releases a file.

REWIND Closes a file and rewinds it. For a magnetic tape file, this means that

the tape is rewound. For a disk file, the record pointer is reset to the

first record of the file.

A WFL job can interrogate the attributes of a file. To do this, the file must first be

declared in the job with certain minimal attributes specified. In addition, the file must be

opened.

File Handling

8600 1047–506 1–17

Examples

The following job examines a file to determine whether it is a COBOL74 or COBOL85

file, and chooses the corresponding compiler:

?BEGIN JOB COBOLCOMP(STRING SYMBOL);

FILE SYMBOLF;

STRING COMPNAME;

SYMBOLF (TITLE=#SYMBOL,KIND=DISK,NEWFILE=FALSE,

DEPENDENTSPECS=TRUE);

OPEN (SYMBOLF);

IF SYMBOLF (FILEKIND) = "COBOL74SYMBOL" THEN

COMPNAME := "COBOL74"

ELSE

COMPNAME := "COBOL85";

COMPILE OBJECT/#SYMBOL WITH #COMPNAME LIBRARY GO;

COMPILER FILE CARD (TITLE=#SYMBOL,KIND=DISK);

?END JOB.

The following subroutine uses the file opening and closing capabilities of WFL to create

dummy files (empty files that can be used to indicate that some particular event has

occurred in the job). Because subroutines cannot contain file declarations, file F is

declared globally.

SUBROUTINE MAKE(STRING FILENAME);

BEGIN

F (TITLE = #FILENAME, KIND = DISK, NEWFILE = TRUE);

OPEN (F);

LOCK (F);

END MAKE;

Refer to “Job Restart after a Halt/Load” in Section 2 for an example of why you might

want to use a job to create dummy files.

File Management

1–18 8600 1047–506

File Management

WFL provides several statements for managing files. These include the following:

• COPY statement

• ADD statement

• CHANGE statement

• REMOVE statement

• SECURITY statement

File Management Statements

The COPY statement copies files on disk or tape. The new copy of a file can be created

with a different usercode or file name, and the file can be copied to other disk or tape

units using library maintenance or to other hosts using distributed systems services

(DSS).

The ADD statement also copies files. However, the ADD statement will not copy a file if

a file with the same title already resides at the destination. Also, the destination specified

must be a disk. The ADD statement is useful for adding a directory of files to a disk

where some of the files are already resident and are to be preserved.

The CHANGE statement changes the names of files on a disk.

The REMOVE statement removes files from disk.

The SECURITY statement changes the security specifications of files on a disk. The

various security settings affect whether the file can be read or changed by tasks running

under other usercodes.

File Management

8600 1047–506 1–19

Examples

The following example copies a file from a disk to a tape, specifying a different usercode

and file name for the new copy:

COPY (ID)FILEA AS (JONES)NEWF FROM ORDS (DISK) TO SAVEA (TAPE);

The following example copies a directory of files to a disk on another host:

ADD (ID)F/= FROM ORDS (DISK) TO SAVEA (DISK, HOSTNAME=MLM);

The following example changes the name of a directory of files residing on a pack named

STORPACK:

CHANGE COMPJOBS/= ON STORPACK TO QCOMPS/=;

The following example removes files from two different packs:

REMOVE MAXERRS FROM PARTS, BADERRS FROM STORPACK;

The following example changes the security of a file to PUBLIC (thus enabling any user

free access to the file):

SECURITY NOVA/DATA/NINER PUBLIC;

Communication

1–20 8600 1047–506

Communication

WFL includes several statements that help inform you about what a job is doing. These

statements include the following:

• DISPLAY statement

• ACCEPT function

• INSTRUCTION statement

• FETCH specification

In addition, these statements enable input to modify the activity of a job.

Communication Statements

The DISPLAY statement can be used to display a message at a specific point during job

execution. The DISPLAY message appears at the ODT, in the job log, and at the CANDE

or MARC station that initiated the job (if it was initiated through CANDE or MARC).

The ACCEPT function will ask you to supply input to the job while it is running. The

ACCEPT function will display the specified message and will wait for you to return a

value by way of the AX (Accept) system command.

The INSTRUCTION statement stores information about the job in a form that you can

display at any time during job execution by using the IB (Instruction Block) system

command.

The FETCH specification stores a message that you can display by using a PF (Print

Fetch) system command, and suspends initiation of the job until the message has been

displayed. The FETCH specification is intended to be used for informing you about what

resources are required by the job.

Communication

8600 1047–506 1–21

Examples

The following example includes DISPLAY statements:

?BEGIN JOB WFLTEST(STRING DAY);

DISPLAY "CALL WILLIS AT EX. 3574 IF RUN-TIME ERRORS OCCUR";

RUN (ODDCOM)OBJECT/COPY/FACTORS(DAY);

DISPLAY "GET INPUT FROM ARCH. TAPE 143 IF FILE REQUIRED";

RUN (ODDCOM)OBJECT/FT/VERIFY(DAY);

?END JOB.

This example runs two programs that are each preceded by a display message informing

the user what to do if certain conditions occur.

The following example shows a use of the ACCEPT function:

?BEGIN JOB;

STRING FN, PK;

FN := ACCEPT("ENTER NAME OF FILE DESIRED");

PK := ACCEPT("ENTER NAME OF PACK DESIRED");

RUN (OPR)DAILY/UPDATE;

FILE IN (TITLE = #FN ON #PK);

?END JOB.

In this example, the values submitted by you are used in a file equation for a RUN

statement. The job could have been written to receive the same values from you by way

of a start parameter list. However, in that case you would have to know in advance what

parameters to supply. The ACCEPT function, on the other hand, displays a message

informing you what type of information to enter next.

Job Format

1–22 8600 1047–506

Job Format

The following features are available to increase the readability of a WFL code:

• Free formatting

• Comments

• Subroutine ending identifiers

Free formatting enables WFL constructs to be entered in any column of a line and

continue over any number of lines. You can use varying amounts of indentation to

indicate the nesting of constructs. However, the invalid character must appear in the first

column.

A percent sign (%) can appear in any column of a line, and will cause the WFL compiler

to ignore the remainder of the line, which can be used for comments.

The identifier that identifies a subroutine can be repeated after the END statement for

that subroutine. In cases where subroutines are nested, this feature helps eliminate

confusion about which subroutine is being ended.

Example

The following example illustrates the use of a nested subroutine ending identifier:

SUBROUTINE SUBOUTER; % Beginning of outer subroutine

BEGIN

SUBROUTINE SUBNESTED; % Beginning of nested subroutine

BEGIN

END SUBNESTED; % End of nested subroutine

END SUBOUTER; % End of outer subroutine

8600 1047–506 2–1

Section 2

Job Initiation

Overview

A program written in WFL is referred to as a job. During execution, a job normally

executes as a task with its own object code file. However, certain statements can be

executed interpretively. This means that no object code file is produced by the WFL

compiler; the statement is executed directly by the WFL compiler.

The statements ALTER, CHANGE, PRINT, REMOVE, RERUN, SECURITY, and START are

executed interpretively in the following situations:

• When one of the above statements is the only statement appearing after the CANDE

WFL command

• When one of the above statements (except the PRINT statement) is entered

individually at an ODT, rather than as part of a job

• When a job originating from a user program by way of an array consists only of one

of the above statements

These situations are described in detail in “START and WFL Commands from CANDE

Sessions,” “Operator Display Terminals (ODTs),” and “User Programs in Other

Languages” later in this section.

A WFL job can initiate other tasks. Examples of tasks are compilations and executions of

user programs. The job task controls the execution of the tasks it initiates.

Sources for Job Initiation

2–2 8600 1047–506

Sources for Job Initiation

The following pages describe how to initiate WFL jobs from each of the possible

sources, and discuss limitations specific to each source.

START and WFL Commands from CANDE Sessions

To run WFL jobs from a CANDE session, use the WFL command or the START

command.

WFL Command

The WFL command causes CANDE to pass any following text to the WFL compiler. This

enables a user to type WFL, followed by a WFL statement or even a job, and transmit

the entire job at once. The WFL job can extend over any number of lines.

The phrases BEGIN JOB and END JOB can be omitted from a job entered after the WFL

command in CANDE. Refer to Section 3, “Job Structure,” for the formal syntax of a job.

Note: Jobs submitted through the CANDE WFL statement cannot include a CLASS,

FETCH, or STARTTIME specification. In addition, the job cannot contain data

specifications, or the INCLUDE control option. Any WFL control options must be

followed by a semicolon (;) to separate them from the rest of the job.

When WFL jobs are initiated from a CANDE session in this way, any messages

generated by the job are displayed at the terminal where the job originated, as well as at

the ODT. The terminal also queues CANDE commands entered while the WFL job was

running and executes them after the job is completed. CANDE control commands the

exception to this rule; they are executed immediately.

The statements CHANGE, PRINT, REMOVE, RERUN, SECURITY, and START are

executed interpretively if one of them is the only statement following the CANDE WFL

command. This means that no object code file is produced by the WFL compiler in these

cases; the statement is executed directly by the WFL compiler.

Sources for Job Initiation

8600 1047–506 2–3

Storing Jobs in Disk Files

WFL jobs can also be saved in files on disk. To do this, you should first use the CANDE

MAKE command to create a file of type JOB. You can then enter the complete job into

the file, either in CANDE, the Editor, or some other text entry utility. For further details,

refer to the CANDE Operations Reference Manual and the Editor Operations Guide.

The question mark (?) preceding the BEGIN JOB and END JOB constructs in column 1

can cause strange results in some text entry utilities. In these cases, it might be

necessary to enter the question mark in column 2, and shift the line to the left later.

More than one job can be stored in a single disk file. The jobs will be compiled and

executed in the order that they appear in the file.

Note: If a file contains more than one job, none of the jobs can include a job parameter

list.

START Command

A WFL job saved in a file can be initiated using the CANDE START command, followed

by the name of the file, and any parameters being passed to the WFL job. Refer to the

CANDE Operations Reference Manual for the detailed syntax of this command.

The START command passes the contents of the file directly to the WFL compiler for

processing. The contents of the file must be a complete WFL job, including the BEGIN

JOB and END JOB constructs. The job can include data specifications, unlike WFL jobs

submitted through the CANDE WFL command.

Any messages from the job are displayed at the originating terminal as well as at the

ODT. However, the terminal remains free to accept any CANDE commands that are

entered and responds immediately, even if they are not control commands.

Sources for Job Initiation

2–4 8600 1047–506

Other CANDE Commands

The following CANDE commands directly invoke WFL statements that have the same

names:

• ADD

• COPY

• PRINT

• START

Therefore, it is not necessary to precede these commands with WFL. Several other

CANDE commands have the same names as WFL statements, but do not invoke WFL,

and in some cases have different syntax or functions than their WFL counterparts. These

statements include:

• ACCESS

• BIND

• CHANGE

• COMPILE

• DO

• LOG

• PASSWORD

• REMOVE

• RUN

• SECURITY

• STOP

To invoke these WFL statements in CANDE, you must precede the statements with the

CANDE WFL command, or include them in a job file and initiate the job with a START

command.

Note: WFL jobs originated from CANDE sessions inherit the usercode of the CANDE

session unless a USERCODE job attribute specification is included in the job. The job

inherits the family specification associated with the usercode it is running under unless a

FAMILY job attribute specification is included in the job.

Sources for Job Initiation

8600 1047–506 2–5

START Statements from Running WFL Jobs

Running WFL jobs can initiate other WFL jobs through the WFL START statement, which

is described in detail in Section 6, “Statements.” The WFL START statement has the

same effect as the CANDE START statement.

Only jobs stored on disk can be initiated by the START statement. Such a job can include

any of the WFL constructs defined in this manual.

Once the job has been started, it has no further connection with its parent job.

Discontinuing the parent job does not affect the job that was started from it, and

termination of the started job also does not affect the parent job.

Any messages generated by the started job are directed to the same source as

messages from the parent job. For example, if the parent job is initiated from CANDE,

then messages from both the parent job and the job started by the parent job would

appear at the originating terminal.

Note: The started job inherits the usercode and family assigned to the parent job

unless the started job includes USERCODE or FAMILY job attribute specifications.

Sources for Job Initiation

2–6 8600 1047–506

Operator Display Terminals (ODTs)

Initiate WFL jobs from an ODT using one of the following methods:

• Use the START statement to initiate a job stored in a disk file.

• Type the complete job at the ODT and transmit the job.

When a complete job is entered at the ODT, it should begin with the BEGIN JOB

construct. It is not necessary to append the END JOB construct to the job, since

WFL will add this automatically.

Note: A complete job entered at an ODT cannot include data specifications. Any

WFL control option must be followed by a semicolon (;) to separate it from the rest

of the job.

A number of WFL statements are recognized by the CONTROLLER and are passed to

WFL automatically, even if they are not preceded by a BEGIN JOB heading. These

statements include the following:

• ABORT

• ACCESS

• ADD

• ALTER

• ARCHIVE

• BEGIN

• BIND

• CATALOG

• CHANGE

• COMPILE

• COPY

• DISPLAY

• PASSWORD

• PROCESS

• PTD

• REMOVE

• RERUN

• RUN

• SECURITY

• START

• USER

• VOLUME

A WFL job initiated at an ODT runs without a usercode unless the job that includes a

USERCODE job attribute specification is run from an ODT with TERM USER specified, or

the HU system command has an associated usercode. The HU system command

designates a usercode for certain distributed systems services Host Services requests if

they come from an ODT that has no terminal usercode assigned to it. The TERM USER

system command controls the format of all displays on the ODT, and associates the

usercode with certain requests initiated at the ODT where the command is entered. See

the System Commands Reference Manual for more details on these commands.

Note: The job, and any tasks initiated by the job, will therefore be unable to access files

residing under usercodes unless their security is PUBLIC. In addition, if the job is running

without a usercode, and no FAMILY specification is included in the job, the FAMILY will

default to DISK = DISK ONLY.

The statements ALTER, CHANGE, REMOVE, RERUN, SECURITY, and START are

executed interpretively if entered individually at an ODT (rather than as part of a job).

When this occurs, no object code file is produced by the WFL compiler; the statements

are executed directly by the WFL compiler and do not enter a job queue. Thus, no queue

attributes, such as FAMILY, are inherited by the job or the statement. These particular

statements are treated as privileged if entered in this way, and can be used to affect files

residing under usercodes.

Sources for Job Initiation

8600 1047–506 2–7

Menu-Assisted Resource Control (MARC)

WFL jobs can be initiated through MARC from the action line of a screen that includes

“COmnd” as one of the screen action hints displayed on line 3, or from the command

input screen, which provides an entry field 15 lines long.

Any WFL statements or a complete WFL job can be initiated from MARC by entering the

word WFL before the statements. The BEGIN JOB and END JOB constructs can be

omitted. However, jobs submitted in this way cannot include data specifications or a

STARTTIME specification.

Note: If WFL control options are included, they must be followed by a semicolon (;). If

any job parameters are included, the job can be compiled for syntax only.

Three WFL statements are recognized by MARC and passed to WFL even if they are not

preceded by WFL. Each statement has the same syntax when it is used in a WFL job.

These statements include:

• START

• COPY

• ADD

Jobs initiated through the START statement can include all of the WFL constructs

defined in this manual. Initiating a WFL job with any of the above statements causes

MARC to enter tasking mode and display the task status screen. Refer to the MARC

Operations Guide for information about how to display and control task progress from

tasking mode.

Distributed Systems Services

WFL jobs can be constructed to take advantage of distributed systems services between

systems in several ways. For more information about how to use distributed systems

services, refer to the Distributed Systems Services Operations Guide and the TCP/IP

Distributed Systems Services Operations Guide.

If a terminal is attached to CANDE, then the names of available BNA hosts can be

displayed using the CANDE ?HN command. The terminal can be transferred to another of

the listed BNA hosts by entering the command:

CONNECT TO <host specification>

When the connection is complete, you can log on under a usercode recognized by the

remote host. While the terminal is connected to the remote host, any commands you

enter are directed to the remote host and executed there. The CANDE WFL and START

commands can thus be used to run jobs on the remote host. The connection is

terminated when you end the session with a BYE command.

Sources for Job Initiation

2–8 8600 1047–506

Even if a terminal is not connected to a remote host, a job initiated at that terminal can

be directed to run at a remote host by beginning the job with the AT <hostname

constant>.

Note: A job including AT <hostname constant> cannot contain a job parameter list or

any BINARY data specifications. Also, the construct before the END JOB construct is

required.

Any messages generated by the job are still routed back to the original terminal, but are

preceded by the name of the system the job is running on.

Examples

The following is an example of a job with an AT <hostname constant> specification. This

job is stored in a file on the user’s own system. However, when the job is initiated, it will

run on the system named LA15D. The job will also look on LA15D for the object code

files of the tasks that it runs.

?AT LA15D BEGIN JOB RUNNIT;

RUN (WALLY)OBJECT/MAKEIT ON SHIPPK;

RUN (ODCON)SNOBOL/REPL ON ORDSPK;

?END JOB.

Tasks can be made to run on different systems than the parent job by specifying the

HOSTNAME attribute after the task initiation statement. The object code files for the

tasks are also searched for on the system specified by the HOSTNAME attribute.

Messages generated by the tasks are still routed back to the original terminal, but are

preceded by the name of the system the job is running on.

?BEGIN JOB RUNNIT;

RUN (WALLY)OBJECT/MAKEIT ON SHIPPK;

HOSTNAME=SF15B;

RUN (ODCON)SNOBOL/REPL ON ORDSPK;

HOSTNAME=SD9A;

?END JOB.

This job runs on the user’s own system. However, it initiates tasks that run on systems

SF15B and SD9A, respectively. The job looks for the object code files for those tasks on

the systems that the tasks are run on.

Files can be copied between HMP NX or A Series hosts, BNA hosts, and hosts

connected to a TCP/IP network by using the WFL COPY statement, which can reference

sources or destinations on remote hosts. For example:

?BEGIN JOB COPYDATA;

COPY *SYSTEM/CRUNCHER AS (WALLY)CRUNCHER/TUESDAY FROM ODDPACK

(KIND=DISK,HOSTNAME=SF15B) TO MODPACK (KIND=DISK,HOSTNAME=LA15D);

?END JOB.

Sources for Job Initiation

8600 1047–506 2–9

This example copies a file from the system named SF15B to the system named LA15D.

The two hosts are BNA hosts and the file is transferred using Host Services file transfer

which is part of the distributed systems services.

User Programs in Other Languages

WFL jobs can be initiated from user programs written in any of several different

programming languages through the use of certain statements. The following table lists

the different programming languages and the statements of each that initiate WFL jobs

from user programs.

Language Language Statement Reference Document

ALGOL ZIP statement ALGOL Programming Reference

Manual, Volume 1: Basic

Implementation

COBOL74 CALL SYSTEM WFL

statement

COBOL ANSI-74 Programming

Reference Manual, Volume 1: Basic

Implementation

COBOL85 CALL SYSTEM WFL

statement

COBOL ANSI-85 Programming

Reference Manual, Volume 1: Basic

Implementation

DCALGOL CONTROLCARD function DCALGOL Programming Reference

Manual

RPG ZIP operation code Report Program Generator (RPG)

Programming Reference Manual,

Volume 1: Basic Implementation

Input submitted from such programs can be in array form or in file form.

Note: If the job submitted is from a data array contained in the program, the job cannot

contain any data specifications, and any WFL control options included in the job must be

followed by a semicolon (;).

If the job is stored in a file external to the program, it can include any WFL construct

defined in this manual. However, if the job contains a job parameter list, it can only be

initiated by a START statement, which can be submitted in array form.

Jobs initiated from user programs inherit the usercode and associated privileges of the

initiating program.

Jobs originating from a user program by way of an array, and that consist of a single

CHANGE, PRINT, REMOVE, RERUN, SECURITY, or START statement, are executed

interpretively. That is, an object code file is not generated, and the statement is executed

directly by the WFL compiler. These statements are not considered privileged unless the

user program is privileged.

Sources for Job Initiation

2–10 8600 1047–506

Magnetic Tapes

The preferred method for initiating jobs stored in files on tape is to first copy the files

onto disk and then start them. The files can be copied using the WFL COPY statement,

either from CANDE or as part of another WFL job. Once the files are on disk, they are

started using the CANDE START command, a START statement in another WFL job, or

the MARC START command.

If a site is attempting to conserve disk space, the job file can be removed from disk after

each use and recopied from the tape whenever it is needed. The job can even include a

REMOVE statement that would remove its own job file from disk after each use.

Job Continuation after a Task Fails

8600 1047–506 2–11

Job Continuation after a Task Fails

A WFL job can be written to take special action in the event that a task terminates

abnormally. The following features are available:

• The ON TASKFAULT statement can be used to direct the job to execute a particular

statement or set of statements whenever a task of the job fails. Refer to the

explanation of the ON statement in Section 6, “Statements,” for details.

• The STATUS, HISTORYCAUSE, and HISTORYTYPE attributes of a task can be

interrogated after a task terminates. An IF statement or CASE statement can be

used to cause different actions to be taken according to the values of these

attributes. Refer to “Interrogating Task Status” in Section 5 for details on STATUS.

HISTORYCAUSE and HISTORYTYPE are both mnemonic task attributes. Refer to

“Interrogating Complex Task Attributes” in Section 5. Task attributes are also

discussed in the Task Attributes Reference Manual.

• The task state expression can be used to determine whether a task terminated

normally. An IF statement or CASE statement can be used to cause different actions

to be taken according to the value of this expression. Refer to “Boolean

Expressions” in Section 7 for details.

The abnormal termination of a task does not affect the job; the job continues to execute

and proceeds to the statement following the one that initiated the task.

Job Restart after a Halt/Load

2–12 8600 1047–506

Job Restart after a Halt/Load

WFL jobs interrupted by a halt/load are automatically restarted after the halt/load.

Execution of the job begins where it left off before the halt/load; if a task was in

progress, the task is restarted. Keep the following considerations in mind when writing a

WFL job to ensure that it will restart properly after a halt/load.

As a WFL job is executing, information about the job is saved off so the job can be

restarted in the event of a halt/load. The process of saving off the job information is

called job rollout. When a job rollout is done, the values of integer, real, Boolean, and

string variables are saved so that these values can be restored to the correct values

when the job is restarted. If a system halt/load occurs while a job is running, the job will

be restarted by the MCP at the most recent successful job rollout.

In general, a job rollout is attempted before each task is run. This way, only the task that

was executing when the halt/load occurred will have to be restarted. However, there are

some restrictions on when a successful job rollout can be accomplished. If any

asynchronous tasks are active when a job rollout is attempted, the job rollout cannot be

completed and will be skipped. If a job rollout has to be skipped, the job can still be

restarted after a halt/load; however, the previous successful job rollout will be retained as

the current restart point.

In the following example, if a halt/load occurs when OBJECT/PROG2 is running, the job

will be restarted at “job rollout point #2”. Thus, the job will be restarted just prior to the

initiation of OBJECT/PROG2.

?BEGIN JOB RESTART/EXAMPLE/1;

% job rollout point #1

RUN OBJECT/PROG1;

% job rollout point #2

RUN OBJECT/PROG2; % Executing OBJECT/PROG2 when halt/load occurs

?END JOB.

For the asynchronous task case, consider the following example:

?BEGIN JOB RESTART/EXAMPLE/2;

% job rollout point #1

PROCESS RUN OBJECT/PROG1; % Note: OBJECT/PROG1 is PROCESSED

% job rollout point #2

RUN OBJECT/PROG2; % Both OBJECT/PROG1 and OBJECT/PROG2

% are active when halt/load occurs

?END JOB.

In this example, the job rollout that is attempted at “job rollout point #2” will not be

successful (because the task OBJECT/PROG1 is active). “Job rollout point #1” will still

be the current restart point. If a halt/load occurs during the execution of

OBJECT/PROG2, the job will be restarted at “job rollout point #1”.

Job Restart after a Halt/Load

8600 1047–506 2–13

A job rollout is attempted before each of the following statements:

• ALTER

• ARCHIVE

• Asynchronous subroutine invocation

• CHANGE

• COMPILE

• COPY

• LOG

• MODIFY

• OPEN

• PRINT

• PTD

• REMOVE

• RUN

• START

• WAIT

If one of the following statements contains an ACCEPT function, a job rollout is

attempted before the statement:

• CASE

• Assignment statement

• DO

• File attribute statement

• IF

• Task attribute statement

• WHILE

A job rollout is also attempted after the WAIT statement. The WAIT statement is the

only statement where a job rollout is executed both before and after the statement. This

occurs because the WAIT statement is often used to synchronize processed tasks, and

attempting the job rollout both before and after the WAIT statement helps to ensure that

a successful job rollout is completed.

Job Restart after a Halt/Load

2–14 8600 1047–506

When waiting for a long task to be completed before initiating a halt/load, it is important

to consider that the job rollout is executed by the WFL job after the task is completed.

Waiting for the task to go to “End of Task” is not sufficient to ensure that the job rollout

is completed. For example:

?BEGIN JOB RESTART/EXAMPLE/3;

% job rollout point #1

PROCESS RUN OBJECT/PROG1;

% job rollout point #2 (not successful because of active task)

WAIT(OK);

% job rollout point #3

?END JOB.

If the intention is to wait until OBJECT/PROG1 is completed before halt loading (so

PROG1 will not have to be restarted), it is important to allow “job rollout point #3” to be

executed. The job would restart at “job rollout point #1”, which obviously would not be

the desired result.

The following example illustrates how to avoid the potential problem by enabling the job

rollout to be successfully completed before the possible halt/load:

?BEGIN JOB RESTART/EXAMPLE/4;

TASK T1,T2;

PROCESS RUN OBJECT/PROG1 [T1]

PROCESS RUN OBJECT/PROG2 [T2]

WAIT (T1 IS COMPLETED);

WAIT (T2 IS COMPLETED)

%%% A successful job rollout will be executed here %%%

WAIT ("Okay to halt/load now", 60);

?END JOB.

However, the contents of most file or task variables are not saved across a halt/load.

They will have the following values:

• Most of the attributes of file variables are returned to what they were immediately

after the original file declaration.

• Most of the attributes of task variables are set to their system default values. This

has the same effect as reinitializing the task variable with the INITIALIZE statement.

Any task attribute assignments that occurred prior to the halt/load are not restored,

including any that were included in the task variable declaration.

The values of constant identifiers that appear in the job parameter list are saved across a

halt/load.

Job Restart after a Halt/Load

8600 1047–506 2–15

ON RESTART Statement

The ON RESTART <statement> form of the ON statement can be used to specify

actions to be taken if job execution is interrupted by a halt/load. Any statement or group

of statements can be specified in the ON RESTART statement. The following kinds of

actions might be desirable:

• File and task variables can be reassigned the correct values.

• Job execution can be restarted at a particular point in the job, by using a GO

statement.

If a halt/load occurs in the middle of a job, job execution restarts at the most recent

successful job rollout. If during the halt/load process the JOBDESC file is removed, jobs

with STARTTIME specifications are also removed. Therefore, no jobs are restarted. For

details, refer to the ??RJ (Remove JOBDESC File) primitive command in the System

Commands Reference Manual.

The ON RESTART statement is processed after a halt/load only if a successful job rollout

occurred after the ON RESTART statement.

Some jobs include statements that interrogate a task variable to find out whether a task

completed successfully or abnormally. However, the value of the task variable is not

retained across a halt/load. An alternative method for storing information about whether a

task completed successfully is to declare a Boolean variable in the job expressly for this

purpose, and assign a value of TRUE or FALSE to the variable after the task completes.

The value of the Boolean variable is saved across a halt/load, so it can always be

interrogated later.

A useful technique for keeping track of exactly how far job execution had progressed

before a halt/load occurred is to declare an integer variable and increment the value of

that variable at several stages during the job. The ON RESTART statement can include

statements that inspect the value of this integer variable and cause different actions to

occur according to the value stored.

Dummy Files

Another method for storing information about job execution is to have the job create

dummy files at specified points during the job execution, or whenever certain conditions

are met. The job can then use the file residence inquiry to establish whether such files

have been created, and make decisions based on their presence or absence.

Refer to “File Handling” in Section 1 for an example of a subroutine that can be used to

create dummy files. The file residence inquiry is described under “Interrogating File

Attributes” in Section 5.

For more detailed information about restarting WFL jobs after a halt/load, see the Task

Management Programming Guide.

Job Restart after a Halt/Load

2–16 8600 1047–506

8600 1047–506 3–1

Section 3

Job Structure

Overview

This section describes the overall structure of a WFL job, and discusses the job attributes

and specifications that can be included at the beginning of a job.

Job Syntax

The following syntax represents a complete WFL job:

<job>

ÄÄÂÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ BEGIN ÄÄ JOB ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄÄÙ ÀÄ AT ÄÄ<hostname constant>ÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ ; ÄÄÄÄÄë

ÀÄ<job title>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<job parameter list>ÄÙ ÀÄ<job disposition>ÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ<statement list>ÄÄÄÄÄë

ÀÄ<job attribute list>ÄÙ ÀÄ<declaration list>ÄÙ

ÄÄÂÄÄÄÄÄÂÄ END ÄÄ JOB ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄÄÙ

Job Structure

A job is composed of three parts:

• Job heading

• Job body

• End of job

Job Heading

The job header initializes the job by means of the following elements:

• construct (optional)

• Hostname constant (optional)

• BEGIN JOB expression (required)

• Job title (optional)

• Job parameter list (optional)

• Job disposition (optional)

• Job attribute list (optional)

Job Syntax

3–2 8600 1047–506

Job Body

The job body contains the operational part of the job and consists of

• Declaration list (optional)

• Statement list

End of Job

The end of job terminates the operation of the job and contains the following elements:

• construct (optional)

• END JOB expression

Job Contents

The contents of WFL jobs are extremely flexible. The only two elements that appear in all

WFL jobs are the BEGIN JOB and END JOB constructs. The WFL compiler adds these

statements around single WFL statements that are entered through CANDE or at the

ODT. The other elements are optional.

Job Format

The formatting of WFL jobs is also flexible. WFL constructs can begin in any column of a

line, can continue over one line onto the next, and can include varying amounts of space

between words. Also, multiple statements can appear on a line, as long as they are

separated by semicolons (;). The only restriction is that the construct must appear in

the first column.

The construct before the BEGIN JOB construct is optional and has no effect on the

job. The construct before the END JOB construct is optional normally, but is required

if an AT hostname constant specification is included in the job. Refer to “Invalid and Valid

Characters” in Section 8 for information about the construct.

Comments can be entered into the job by preceding them with a percent sign (%). Any

input following the percent character on a line is ignored by the WFL compiler. However,

input that precedes the percent sign on a line is treated as part of the job.

WFL control options can be included anywhere in the job, as long as they appear on a

line with a dollar sign ($) in the first or second column. These options are discussed in

Section 9, “WFL Control Options.”

Note: A WFL job must be entered in all uppercase letters. Only comments or strings

can contain lowercase letters.

Job Syntax

8600 1047–506 3–3

AT Hostname

The AT hostname constant specification causes a job initiated on one system to be

compiled and run on another system.

The WFL compiler at the receiving host system compiles the job; the sending host does

not analyze the contents of the job, except for the END JOB construct. If the END JOB

construct is missing, an “UNEXPECTED END OF FILE” error message is issued.

The hostname specified must be an available host in a BNA or Open Systems

Interconnection (OSI) network.

If the host specified is not available, the job compilation is aborted and the error message

“UNKNOWN HOST SPECIFIED” is displayed. The CANDE ?HN command or the

HOSTNAME (Host Name) system command can be used before the job is started to

determine what BNA hosts are available. The CANDE ?AT local host NW OSIGATEWAY

command or the NW OSIGATEWAY system command can be used to determine what

OSI hosts are available.

A null character within a quoted string causes the transferred job to be incorrectly

terminated, which causes erroneous syntax errors at the receiving host. This incorrect

termination occurs because the sending host does not analyze the contents of the job;

the sending host transfers data to the receiving host only until a null character is reached.

Using the START FOR SYNTAX statement is not allowed for jobs that include an AT

hostname constant specification. Doing so generates the following syntax error:

START FOR SYNTAX IS ONLY VALID FOR LOCAL HOST

Example

The following job will run at the system named SF6B:

?AT SF6B BEGIN JOB ADDIT;

?END JOB.

Job Title

3–4 8600 1047–506

Job Title

ÄÄ<file title constant>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The job title specifies the name of the job. The job name appears in the

• BOJ and EOJ messages displayed by the job

• Active entry display at the ODT

• Job summary generated by a job

• System log

The job title must be included if there is a job parameter list or job disposition in the job;

otherwise, the job title is optional.

Though the syntax for a job title is the same as that for a file title constant, the job title

does not have to be the name of any file. There is no connection between the job title of

a job and the title of the file it is stored in. For the syntax of a file title constant, see “File

Names, Titles, and Directories” in Section 8.

The job name can also be assigned by including the NAME attribute in the job attribute

list for the job. Note that the NAME attribute overrides the job name in the <job title>.

If neither a job title nor a NAME job attribute is included in the job, the WFL compiler

assigns a name to the job.

Examples

The following are examples of job headings that include valid job titles:

?BEGIN JOB RUNPROG;

?BEGIN JOB DATA/SURVEYOR;

?BEGIN JOB (WALLY)MENU/PLAN;

?BEGIN JOB (LAO)OLD/DOC ON FORMSPK;

Job Parameter List

8600 1047–506 3–5

Job Parameter List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ( ÄÁÄÂÄ<Boolean parameter declaration>ÄÂÄÁÄ ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<integer parameter declaration>Ä´

ÃÄ<real parameter declaration>ÄÄÄÄ´

ÀÄ<string parameter declaration>ÄÄÙ

ÄÄ BOOLEAN ÄÄ<Boolean formal parameter>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄ´

ÀÄ OPTIONAL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ DEFAULT ÄÄ = ÄÄ<Boolean constant expression>ÄÙ

ÄÄ INTEGER ÄÄ<integer formal parameter>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄ´

ÀÄ OPTIONAL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ DEFAULT ÄÄ = ÄÄ<integer constant expression>ÄÙ

ÄÄ REAL ÄÄ<real formal parameter>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄ´

ÀÄ OPTIONAL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ DEFAULT ÄÄ = ÄÄ<real constant expression>ÄÙ

ÄÄ STRING ÄÄ<string formal parameter>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ´

ÀÄ OPTIONAL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ DEFAULT ÄÄ = ÄÄ<string constant expression>ÄÙ

ÄÄ<Boolean constant identifier>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ<integer constant identifier>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ<real constant identifier>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ<string constant identifier>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Job Parameter List

3–6 8600 1047–506

Explanation

A job parameter list declares constant identifiers and assigns them the values supplied in

the START statement that initiated the job. The constant identifiers retain their original

values throughout the job. They can be one of the following types:

• BOOLEAN

• INTEGER

• REAL

• STRING

These constant identifiers can be used in a WFL job in most of the places a constant or

an expression of the appropriate type is permitted. (For example, a Boolean constant

identifier can be used wherever a Boolean constant, Boolean constant expression, or

Boolean expression is permitted.)

The keyword OPTIONAL indicates that an actual parameter does not need to be passed

for that job parameter. If an actual parameter is not passed, the default values are

assigned as follows:

Type Default Value

Boolean FALSE

Integer 0

Real 0

String "" (two double quotation marks)

Default values can also be specified with the DEFAULT clause following the keyword

OPTIONAL. The specified default value is ignored if an actual parameter is provided.

A job parameter list can only be used in WFL jobs that are stored on disk and initiated

through a CANDE, MARC, or WFL START statement. If a job initiated from another

source includes a job parameter list, then it must be compiled for syntax only (see the

description of the SYNTAX job disposition later in this section).

A job that includes an AT hostname constant specification cannot have a job parameter

list, unless all the job parameters are optional. When more than one job is stored in a disk

file, none of the jobs can contain job parameter lists.

Job Parameter List

8600 1047–506 3–7

Example

Consider the statement START (WALLY)RUNPROG(23.8, 7), which initiates the following

job:

?BEGIN JOB RUNPROG (REAL VAL1, REAL VAL2);

REAL INVAL;

INVAL := VAL2 * VAL2;

RUN OBJECT/WALLY/COUNTER(VAL1);

RUN OBJECT/WALLY/COUNTER(INVAL);

?END JOB.

This job runs the program OBJECT/WALLY/COUNTER twice, first with a parameter value

of 23.8, and then with a parameter value of 49 (because INVAL was assigned the square

of the VAL2 parameter).

Job Disposition

3–8 8600 1047–506

Job Disposition

ÄÄÂÄÄÄÄÄÄÄÂÄ SYNTAX ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ FOR ÄÙ

Explanation

The SYNTAX job disposition compiles a job for syntax checking only. When the job is

initiated, the WFL compiler simply compiles it and displays a list of any syntax errors in

the job. This job disposition is beneficial when you only need to debug a job.

Example

The following is an example of a job heading that includes a SYNTAX job disposition:

?BEGIN JOB GEO/ANLYS FOR SYNTAX;

Job Attribute List

8600 1047–506 3–9

Job Attribute List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ<task attribute assignment>ÄÂÄ ; ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<class specification>ÄÄÄÄÄÄÄ´

ÃÄ<fetch specification>ÄÄÄÄÄÄÄ´

ÀÄ<starttime specification>ÄÄÄÙ

Explanation

The job attribute list assigns task attributes and job specifications to the job. The CLASS

specification, FETCH specification, and STARTTIME specification can only be applied to a

job and are described under their own headings later in this section.

The syntax for task attribute assignment is described in Section 5, “Task Initiation,” later

in this manual. The types and the meanings of the task attributes recognized by the WFL

compiler are described in the Task Attributes Reference Manual.

Attributes not assigned to values in the job attribute list are assigned values by the

system on the following basis:

• Certain attributes inherit values associated with the usercode the job is originated

from, such as the CLASS, CHARGECODE, FAMILY, CONVENTION, PRIORITY, and

USERCODE attributes. These values are stored in USERDATA locator nodes in the

USERDATAFILE. For information about the USERDATAFILE, refer to the Security

Administration Guide.

• Other attributes can inherit values associated with the class (or queue) of the job. A

class can have default values and/or maximum values specified for the PRIORITY,

MAXPROCTIME, MAXIOTIME, or ELAPSEDLIMIT attributes. A job is discontinued if

the job attribute list specifies greater resource limits than those associated with the

class of the job.

• Attributes assume their default values if they are not included in the job attribute list

and do not receive values from the usercode or class of the job. The attributes that

limit resource usage default to their maximum possible values.

Task attributes can also be assigned to specific tasks initiated by a job. Refer to the

Section 5, “Task Initiation,” for a description of how to assign task attributes to specific

tasks.

Task attributes associated with a job can be changed or interrogated later in the job by

using the MYJOB predeclared task variable.

Note: A string primary cannot be used in job-related task attribute assignments unless

you use the MYJOB or MYSELF predeclared task variable syntax. Refer to “MYJOB and

MYSELF Predeclared Task Variables” in Section 5 for details.

Job Attribute List

3–10 8600 1047–506

Resource-Limiting Attributes

Resource-limiting attributes affect the total resources available to a job and all its tasks

when such attributes are included in the job attribute list. Resource-limiting attributes

include the following:

• ELAPSEDLIMIT

• MAXIOTIME

• MAXLINES

• MAXPROCTIME

• MAXWAIT

• PRINTLIMIT

• PUNCHLIMIT

While these attributes can also be set for specific tasks, the accumulated resource usage

of the job and all its tasks cannot exceed the values set for these attributes for the job.

Some of the job attribute values are inherited by the tasks initiated by a job. The

inheritance status of each attribute is listed in the Task Attributes Reference Manual.

The HOSTNAME task attribute has no effect when it is used in a job attribute list, but an

AT hostname constant specification can be used instead. Refer to “AT Hostname”

earlier in this section for details.

If a particular task attribute is assigned values more than once in a job attribute list, the

last assignment overrides the previous ones.

The job attribute list is terminated by the appearance of any construct that is not a job

attribute assignment.

USER is accepted as a synonym for the USERCODE task attribute when it is entered as

part of a job attribute list. If the USER statement is the first statement of a job, it is

interpreted as part of the job attribute list rather than as an executable statement. The

specified USERCODE is validated during the compilation as a new usercode logging on

for the duration of the job execution.

Note: Changing the usercode of the job causes the job to run under the new usercode

with job attributes specified in the USERDATAFILE. If the usercode of the job is changed,

job messages will stop appearing at the originating terminal even though the job

continues to execute normally.

File equations cannot be included in the job attribute list. A statement beginning with

FILE is interpreted as a file declaration and terminates the job attribute list.

Job Attribute List

8600 1047–506 3–11

Example

The following example job includes a number of common job attribute assignments:

?BEGIN JOB COMPJOB;

CLASS = 3;

USERCODE = JOHN/JUAN;

CHARGECODE = SHIPPING;

MAXPROCTIME = 60;

PRIORITY = 80;

RUN (WALLY)POSTAGE/SUMMARY ON SHIPPK;

?END JOB.

CLASS Specification

3–12 8600 1047–506

CLASS Specification

ÄÄÂÄ CLASS ÄÂÄ = ÄÄ<integer constant expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ QUEUE ÄÙ

Explanation

The CLASS specification assigns the number of the queue desired for the job. (QUEUE is

a synonym of CLASS.)

For more information on managing WFL jobs in queues, refer to the System

Administration Guide.

Examples

The following job extracts include CLASS specifications:

?BEGIN JOB COMP;

CLASS = 5;

?BEGIN JOB CLASSVAL(INTEGER CL);

CLASS = CL;

FETCH Specification

8600 1047–506 3–13

FETCH Specification

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ FETCH ÄÄ = ÄÁÄ<string constant expression>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The FETCH specification provides operators with information about the job.

One or more strings can be included in the FETCH specification. Initiation of a job is

suspended if it includes a FETCH specification; the job appears in the waiting entries list

at the ODT with a “REQUIRES FETCH” message. The FETCH messages can be

displayed using the PF (Print Fetch) system command. The job can be reactivated using

the CANDE OK command or the OK system command.

If the system option 19 (NOFETCH) is set, the FETCH attribute does not suspend job

initiation. However, it is still possible to use the PF system command to display the fetch

message associated with a job. System options are set or displayed using the OP

(Options) system command.

Example

?BEGIN JOB UPDATE;

FETCH = "THIS JOB NEEDS THREE TAPE DRIVES";

RUN NIGHTLY/UPDATE;

?END JOB.

STARTTIME Specification

3–14 8600 1047–506

STARTTIME Specification

ÄÄ STARTTIME ÄÄ = ÄÄ<starttime spec>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄÂÄ<time>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ + ÄÄ<time interval>ÄÙ ÀÄ ON ÄÂÄ<date>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ + ÄÄ<day interval>ÄÙ

<time>

ÚêÄÄÄÄÄÄÄÄÄÄÄÄ¿ ÚêÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄ/2\Ä<digit>ÄÁÄ : ÄÄÄ/2*\Ä<digit>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

<date>

ÄÄÂÄ<mm>ÄÄ / ÄÄ<dd>ÄÄ / ÄÂÄ<yy>ÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<yyyy>Ä´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÃÄÁÄ/5*\Ä<digit>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ/7*\Ä<digit>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

<mm>

<dd>

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄ /2\ ÄÄ <digit> ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

<yy>

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄ /2\ ÄÄ <digit> ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

<yyyy>

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄ /4*\ ÄÄ <digit> ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The STARTTIME specification delays job initiation until the specified start time.

The time construct specifies the time of day on a 24-hour clock. The time and time

interval constructs are of the form HH: MM, where HH specifies the hour (or number of

hours) and MM specifies the minute (or number of minutes). HH must be less than 24,

and MM must be less than 60. The minute values must be 2-digit numbers. If a time

interval is specified, that time interval is added to the current time.

The day, hour, and month values can either be a 1-digit or a 2-digit number.

STARTTIME Specification

8600 1047–506 3–15

The date construct can be input either in the Gregorian format: mm/dd/yy or mm/dd/yyyy,

or the Julian format: yyddd or yyyyddd. If a 5-digit <Julian date> is used as the

STARTTIME value, the first two digits signify the year and the last three digits signify the

day of the year. If a 7-digit <Julian date> is used, the first four digits signify the year

(including the century) and the last three digits signify the day of the year. For example, if

you input either 94293 or 1994293, they will both equal day 293 of 1994.

If a day interval is specified, that number of days is added to the current date.

If the time is specified without a date or day interval, the current date is used.

The FS (Force Schedule) system command can be used to cause job initiation to proceed

immediately, without waiting for the specified start time. For a description of the FS

command, refer to the System Commands Reference Manual.

Examples

The following job begins execution after 10:00 p.m. on March 20, 1990:

?BEGIN JOB EXAMPLE1;

STARTTIME = 22:00 ON 03/20/90;

?END JOB.

The following job begins execution a minimum of 1 hour and 30 minutes after entering

the system:

?BEGIN JOB EXAMPLE2;

STARTTIME = +1:30;

?END JOB.

The following job is executed on host BLUE and begins execution after 11:00 a.m.

according to the system clock on host BLUE:

?AT BLUE BEGIN JOB;

STARTTIME = 11:00;

?END JOB.

Declaration List

3–16 8600 1047–506

Declaration List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄ<declaration>ÄÄ ; ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

Declarations define constants, variables, subroutines, and global data specifications.

Declarations of variables can also include initial value assignments. The following types of

variables are available in WFL: BOOLEAN, INTEGER, REAL, STRING, FILE, and TASK. For

details about the declarations available in WFL, refer to Section 4, “Declarations.”

All declarations for the job must precede all statements in the job, and the declarations in

a subroutine must precede all the statements in that subroutine.

More than one declaration can appear on a line, as long as each declaration is followed by

a semicolon (;).

Example

The following job segment illustrates the use of declarations:

CONSTANT DEBUG = FALSE;

BOOLEAN TFVAL,

SUBTVALU;

FILE FILE1(TITLE=(ODCOM)FIXIT ON PACK);

INTEGER INTVAL := 43;

REAL RLVAL := 19.67,

RLVAL2 := 16.8;

STRING STRNGVL := "Test Run";

TASK DOUBAT (PRIORITY=75,INFILE(TITLE=(WALLY)DATA/SAVER));

DATA INPUT/PREP

128

? % End of data

SUBROUTINE PROVIT;

BEGIN

RUN (RAJA)DATA/PREP(TFVAL,INTVAL,STRNGVL,RLVAL);

FILE INPUT (TITLE=INPUT/PREP,KIND=READER);

END PROVIT;

Statement List

8600 1047–506 3–17

Statement List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ; ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ<statement>ÄÄÄÄÄÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ<label identifier>ÄÄ : ÄÁÄÙ

Explanation

The statements in a WFL job are grouped together in a statement list. More than one

statement can appear on a line, while a lengthy statement can continue across several

lines. Individual statements are distinguished by a statement separator.

The usual statement separator is a semicolon (;) appearing at the end of a statement.

However, an invalid character at the start of a line also acts as a statement separator.

Each statement can be preceded by one or more label identifiers. These label identifiers

can then be referred to by GO statements in the job. GO statements transfer control to

the point in the job where the specified label identifier appears.

Refer to Section 6, “Statements,” for descriptions of all the statements available in WFL.

Examples

In this first example, the semicolon signals the end of a statement.

BEGIN JOB SEPARATOR/EXAMPLE1;

IF DECIMAL( TIMEDATE(HHMMSS) ) < 120000 THEN

DISPLAY "Good Morning, it is now: "

& TIMEDATE(DISPLAY)

ELSE

DISPLAY "Good Afternoon, it is now: "

& TIMEDATE(DISPLAY);

WAIT(5); DISPLAY "Bye";

?END JOB.

In this next example, the invalid character—the question mark (?)—in the first column of

a statement implies the end of the previous statement. A semicolon must be used to

separate multiple statements appearing on a single line.

?BEGIN JOB SEPARATOR/EXAMPLE2

?IF DECIMAL( TIMEDATE(HHMMSS) ) < 120000 THEN

DISPLAY "Good Morning, it is now: "

& TIMEDATE(DISPLAY)

ELSE

DISPLAY "Good Afternoon, it is now: "

& TIMEDATE(DISPLAY)

?WAIT (5); DISPLAY "Bye"

?END JOB.

Statement List

3–18 8600 1047–506

The following example shows the use of statement label identifiers:

?BEGIN JOB LABEL/EXAMPLE3;

STRING S;

RETRY:

COPY X AS Y;

IF FILE Y ISNT RESIDENT THEN

BEGIN

AX:

S:= ACCEPT("FILE Y NOT COPIED. AX: RETRY, OR AX: SKIP");

IF S = "RETRY" THEN

GO TO RETRY

ELSE IF S = "SKIP" THEN

ABORT

ELSE

GO TO AX; % Ask again.

END;

?END JOB.

WFL Job Example

8600 1047–506 3–19

WFL Job Example

The following example illustrates a complete WFL job:

?BEGIN JOB EXAMPLE (STRING TESTNAME,INTEGER TESTNUMBER);

NAME=EXAMPLE/#STRING(TESTNUMBER,*); % Job attribute

USERCODE = WFL/MANUAL; % Job attribute

CLASS = 2; % Job attribute

TASK TCOMP, TRUN; % Variable declaration

COMPILE #(TESTNAME & STRING(TESTNUMBER,*))[TCOMP] WITH ALGOL[TRUN] GO;

COMPILER DATA CARD % The COMPILE statement is

BEGIN % followed by a local data

INTEGER I; % specification containing the

DISPLAY ("P IS RUNNING"); % program being compiled.

DISPLAY ("NOW ABORT"); % For information about local

I=I/0; % data specifications, see the

END. % "Task Initiation" section.

? % End of data.

IF TCOMP IS COMPILEDOK THEN % Displays message if compile

DISPLAY "COMPILED OK" % is successful.

ELSE ABORT "*DID NOT COMPILE"; % Aborts job if compile

% fails.

IF TRUN IS COMPLETEDOK THEN % Displays messages if run

DISPLAY "RAN OK" % is successful; otherwise,

ELSE ABORT "** RUN ABORTED"; % aborts job.

?END JOB.

WFL Job Example

3–20 8600 1047–506

8600 1047–506 4–1

Section 4

Declarations

Overview

Declarations define constants, variables, subroutines, and global data specifications.

Statement label identifiers are not declared. Refer to “Statement List” in Section 3 for a

discussion of label identifiers.

Declaration Syntax

The following syntax represents the declarations available in a WFL job:

ÄÄÂÄ<constant declaration>ÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<Boolean declaration>ÄÄÄÄÄÄÄ´

ÃÄ<integer declaration>ÄÄÄÄÄÄÄ´

ÃÄ<real declaration>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<string declaration>ÄÄÄÄÄÄÄÄ´

ÃÄ<file declaration>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<task declaration>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<subroutine declaration>ÄÄÄÄ´

ÀÄ<global data specification>ÄÙ

Explanation

All declarations in a job must follow the job attribute list and must precede any

statements. All declarations in a subroutine must follow the BEGIN statement for the

subroutine and must precede any executable statements in the subroutine.

Declarations can occur in any order.

Declaration Syntax

4–2 8600 1047–506

Scope of Declarations

Declarations can occur either at the job level or within subroutines. Declarations

occurring at the job level can define:

• Global variables

• Subroutines

• Global data specifications

Items declared at the job level can be referenced anywhere in the job, including in any of

the subroutines.

Variables and subroutines declared within a subroutine are local to that subroutine. They

can only be used in the subroutine they are declared in, and in subroutines nested within

that subroutine. Local variables are reinitialized each time the subroutine is invoked.

Note: A variable or subroutine cannot be referenced before its declaration. For

example, a subroutine cannot make use of a globally declared variable unless the

declaration of that variable occurs before the declaration of the subroutine.

Special care should be taken when assigning values to a global variable in an

asynchronous subroutine. Refer to the “PROCESS Statement” in Section 6,

“Statements,” for further information.

Variable Initialization

The initial value of a variable can be specified in the declaration; if it is not, the default

value for that variable type is applied to the variable. The initial value of a variable is

stored before the execution of the first statement in the job or subroutine.

Boolean, integer, real, and string variables retain their values across a halt/load. However,

the contents of file and task variables are not saved. Refer to “Job Restart after a

Halt/Load” in Section 2 for details.

The INITIALIZE statement assigns a value of NEVERUSED to the STATUS task attribute

of the specified task variable, and restores the default values to all other task attributes

and file equations associated with that task variable.

Constant Identifiers

8600 1047–506 4–3

Constant Identifiers

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ CONSTANT ÄÁÄ<constant declaration element>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄÂÄ <Boolean constant identifier> = <Boolean constant expression> ÄÂÄÄ´

ÃÄ <integer constant identifier> = <integer constant expression> Ä´

ÃÄ <real constant identifier> = <real constant expression> ÄÄÄÄÄÄÄ´

ÀÄ <string constant identifier> = <string constant expression> ÄÄÄÙ

Explanation

A constant declaration declares one or more constant identifiers and assigns their value.

A constant identifier can be one of the following type:

• Boolean

• Integer

• Real

• String

The constant declaration enables constant values to be referenced by name rather than

by specifying the actual values throughout the job.

The type of each constant identifier being declared is determined by the type of the

constant expression to the right of the equal sign (=). The constant expression can be

specified using literal values, previously declared constant identifiers, and job

parameters.

The values of constant identifiers are retained across a halt/load.

Example

The following example represents the use of constant identifiers:

CONSTANT

NAME = "ABCDEFGHIJKLMNOPQRSTUVWXYZ-_",

NUMBERS = "0123456789",

PI = 3.14159,

DEBUG = FALSE,

MAXRETRY = 10,

MAXSTRINGCHARS = 256,

UC = "GEORGE",

INPUTNAME = "INPUT/1",

PK = "USERS",

INPUTTITLE = "(" & UC & ")" & INPUTNAME PK;

Boolean Variables

4–4 8600 1047–506

Boolean Variables

ÄÄ BOOLEAN ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄ<Boolean identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄÄ´

ÀÄ := ÄÄ<Boolean constant expression>ÄÙ

Explanation

A Boolean declaration declares a variable of type BOOLEAN. The default initial value of a

Boolean variable is FALSE.

If the := Boolean constant expression clause is specified for a Boolean identifier, this

Boolean constant expression is used as the initial value for that Boolean identifier.

The values of Boolean variables are saved across a halt/load and are restored when the

job restarts.

Integer Variables

8600 1047–506 4–5

Integer Variables

ÄÄ INTEGER ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄ<integer identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄÄ´

ÀÄ := ÄÄ<integer constant expression>ÄÙ

Explanation

An integer declaration declares a variable of type INTEGER. The default initial value of an

integer variable is 0.

If the := integer constant expression clause is specified for an integer identifier, this

integer constant expression is used as the initial value for that integer identifier.

The values of integer variables are saved across a halt/load and are restored when the job

restarts.

Real Variables

4–6 8600 1047–506

Real Variables

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ REAL ÄÁÄ<real identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄ´

ÀÄ := ÄÄ<real constant expression>ÄÙ

Explanation

A real declaration declares a variable of type REAL. The default initial value of a real

variable is 0.

If the clause := real constant expression is specified for a real identifier, this real constant

expression is used as the initial value for that real identifier.

The values of real variables are saved across a halt/load and are restored when the job

restarts.

String Variables

8600 1047–506 4–7

String Variables

ÄÄ STRING ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄ<string identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄÄÄÄ´

ÀÄ := ÄÄ<string constant expression>ÄÙ

Explanation

A string declaration declares a variable of type STRING. The default initial value of a string

variable is a null string ("").

The values of a string variable are saved across a halt/load.

If the := string constant expression clause is specified for a string identifier, this string

constant expression is used as the initial value for that string identifier.

Example

The following example illustrates the declaration of string variables:

STRING STR1, STR2;

STRING STR3 := "STRVAL";

File Variables

4–8 8600 1047–506

File Variables

ÄÄ FILE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄ<file identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ ( ÄÁÄ<file attribute assignment>ÄÁÄ ) ÄÙ

Explanation

A file declaration defines a logical file with the specified file attributes. A file declared in a

WFL job can be used in either of two ways:

• To enable file attribute inquiries.

If the declared file is associated with a physical file, the file identifier can be used in

expressions that return the values of attributes of the physical file. This subject is

discussed under “Interrogating File Attributes” in Section 5.

• To enable a task to use a declared file.

If a file is declared in a global file assignment, the global file assignment causes a

task to use the declared file in place of a file that the task would normally use. This

subject is discussed under “File Equations” in Section 5.

WFL cannot directly read from or write to the declared file. However, the file equation

capabilities of WFL do provide considerable control over the choice of files that will be

used by a task. Refer to “File Equations” in Section 5 for further details.

Note: File declarations cannot occur in a subroutine.

The WFL job can also include input data for a task, in the form of data specifications.

Refer to “Global Data Specifications” later in this section and “Local Data Specifications”

in Section 5 for further details.

File attributes included in a file declaration must be assigned constants or constant

expressions. Attributes of type name, file name, or title must be assigned constants only.

File attribute values associated with a file variable are not saved across a halt/load. Refer

to “Job Restart after a Halt/Load” in Section 2 for further details.

Note: The use of the file identifier SUMMARY should be avoided for printer files. If a

printer file is declared in WFL with a file identifier of SUMMARY, and a job summary is

generated with the default title of SUMMARY, the printer file declared in WFL will be

lost. This occurs because the job summary file will overwrite the file declared in WFL.

To create a printer file in WFL with the file identifier SUMMARY, either use the

JOBSUMMARY task attribute to suppress the job summary, or use the

JOBSUMMARYTITLE task attribute to assign a different name to the job summary file.

Task Variables

8600 1047–506 4–9

Task Variables

ÄÄ TASK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄ<task identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄÄ´

ÀÄ ( ÄÄ<task identifier assignment>ÄÄ ) ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ<task attribute assignment>ÄÂÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<file equation>ÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

The task declaration declares task variables, which can be associated with particular

tasks in a task initiation statement.

If a task initiation statement includes a task variable, then any task attribute assignments

or file equations that have been specified for that task variable are applied to the task.

The values assigned to file and task attributes in a task declaration must be constants or

constant expressions. Attributes of type name, file name, or title must be assigned

constants only.

Any task attribute values or file equations associated with a task variable are not saved

across a halt/load. Refer to “Job Restart after a Halt/Load” in Section 2 for further details.

Task variables can be assigned task attribute values or file equations later in the job by

the task assignment statement. Refer to the assignment statement in Section 6,

“Statements,” for a description of the task assignment statement.

The task variable can also be used for inquiries about the values of any task attributes

associated with the task, including those task attributes that record task status and task

history. This is possible by using various WFL expressions, which are described in

Section 7, “Expressions.”

WFL provides two predefined task variables. The following task variables can be used to

interrogate the values of attributes in the job:

• MYSELF

• MYJOB

Refer to “Using Task Variables” in Section 5 for a discussion of the uses of the task

variables, including the MYSELF and MYJOB task variables.

Subroutines

4–10 8600 1047–506

Subroutines

ÄÄ SUBROUTINE ÄÄ<subroutine identifier>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄë

ÀÄ<subroutine parameters>ÄÙ

ëÄ ; ÄÂÄ<statement>ÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<subroutine block>ÄÙ

subroutine parameters>

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ( ÄÁÄÂÄ BOOLEAN ÄÄ<Boolean identifier>ÄÂÄÄÄÄÄÄÄÄÄÂÄÂÄÁÄ ) ÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ VALUE ÄÙ ³

ÃÄ INTEGER ÄÄ<integer identifier>ÄÂÄÄÄÄÄÄÄÄÄÂÄ´

³ ÀÄ VALUE ÄÙ ³

ÃÄ REAL ÄÄ<real identifier>ÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄ´

³ ÀÄ VALUE ÄÙ ³

ÃÄ STRING ÄÄ<string identifier>ÄÂÄÄÄÄÄÄÄÄÄÂÄÄÄ´

³ ÀÄ VALUE ÄÙ ³

ÃÄ FILE ÄÄ<file identifier>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ TASK ÄÄ<task identifier>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄ BEGIN ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ END ÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ<declaration list>ÄÙ ÀÄ<statement list>ÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<subroutine identifier>ÄÙ

Explanation

A subroutine declaration identifies a series of statements that are executed when the

subroutine is invoked by a subroutine invocation statement. The subroutine invocation

statement is described in Section 6, “Statements.”

The simplest form of a subroutine consists of the subroutine heading, followed by a

single statement. Declarations and multiple statements can be included in the

subroutine, but they must be bracketed by the words BEGIN and END.

Any kind of WFL declaration can be included in a subroutine except for file declarations

and global data specifications. However, subroutines can include local data

specifications, and references to global data specifications and files that are declared

globally. Variables declared in a subroutine are local to that subroutine (refer to “Scope of

Declarations” earlier in this section).

The WFL statements are described in Section 6, “Statements.”

WFL enables a subroutine identifier to be repeated after the end of the subroutine. This

feature helps create WFL jobs that are easier to read, especially in cases where nested

subroutines occur. If a subroutine identifier is specified after END, it must be the same

subroutine identifier specified at the start of the declaration.

Subroutines

8600 1047–506 4–11

A subroutine declaration can include another subroutine declaration within itself. This is

referred to as nesting. Subroutines can be nested to a maximum of 10 levels.

Note: WFL jobs that have nested subroutines can result in larger code files due to the

new Long Name Call/LNMC, Long Value Call/LVLC code, which replaces Name

Call/NAMC, Value Call/VALC and uses more bytes. If the WFL compiler issues a warning

message that a code segment exceeds its capacity, then you must split the statements

in that subroutine into multiple subroutines. Ignoring the warning message can result in

the initiation or compilation of a WFL job being aborted.

Subroutine Parameters

The subroutine parameters specification can be included in the subroutine heading to

declare parameters for the procedure. These parameters are assigned values taken from

the statement that invoked the subroutine. The parameters are treated as local variables

within the subroutine; they can be interrogated or assigned new values anywhere within

the subroutine or within any subroutines nested within it.

Declarations in a subroutine cannot declare an identifier that has the same name as any

of the parameters of that routine. Each parameter in the parameter list must be preceded

by a keyword specifying the parameter type.

A parameter is considered to be call-by-reference unless it is followed by the word

VALUE, which indicates that the parameter is call-by-value. Task and file variables can

only be call-by-reference.

Note: Any changes made to the value of a call-by-reference parameter in the course of

the subroutine also change the value of the variable that was passed to that parameter.

By contrast, any changes made to the value of a call-by-value parameter in the course of

the subroutine do not affect the value of the variable that was passed to that parameter.

If a constant or an expression is passed as a parameter in the subroutine invocation

statement, that parameter is passed by value whether or not VALUE is specified for that

parameter. When a real parameter is passed to an integer in a subroutine call, it requires

integer truncation and treats the real parameter as an expression. Because an expression

is passed as a parameter, that parameter is passed by value.

When a parameter is a string expression, the string expression can contain up to

1026 characters. Within the subroutine, however, the string parameter cannot be

assigned directly to a string variable, because a string variable has a maximum length of

256 characters.

Example

The following example illustrates the use of subroutines:

?BEGIN JOB SUBSHOW;

INTEGER VAL1 := 7, % Global variable declarations

VAL2 := 11;

% Begin subroutine declaration

Subroutines

4–12 8600 1047–506

SUBROUTINE FIRSTSUB(INTEGER PARAM1, INTEGER PARAM2 VALUE);

BEGIN

PARAM1 := PARAM1 * 2; % Changes made to the values of the

PARAM2 := PARAM2 * 2; % parameters

END FIRSTSUB;

% End subroutine declaration

FIRSTSUB(VAL1,VAL2); % Subroutine invocation

RUN (RAJA)AREA/MEASURE(VAL1,VAL2); % Task initiation

?END JOB.

In this example, the global variables VAL1 and VAL2 are assigned values of 7 and 11,

respectively. The subroutine invocation statement passes the variables VAL1 and VAL2

as values for the parameters PARAM1 and PARAM2. PARAM1 is therefore assigned a

value of 7, and PARAM2 is assigned a value of 11. The subroutine contains statements

that double the values of these parameters to 14 and 22, respectively.

The RUN statement that follows the subroutine invocation statement passes VAL1 and

VAL2 to the program (RAJA)AREA/MEASURE. The values the program receives are 14

and 11. This occurs because the change made to the value of the call-by-reference

parameter PARAM1 also affects the global variable VAL1 that was passed to it. The

change made to the call-by-value variable PARAM2 does not affect VAL2.

Global Data Specifications

8600 1047–506 4–13

Global Data Specifications

ÄÄÂÄ DATA ÄÄÄÂÄ<file name constant>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ%

ÀÄ EBCDIC ÄÙ

ÄÄ<data images>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ%

ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

One or more card images or records of EBCDIC data.

Explanation

A global data specification contains data that can be used as input by programs initiated

in the job. The global data specification is read as if it were a card reader input file, and

can be closed and reopened or read by more than one task.

The file name constant identifies the global data specification. The file name constant

cannot contain a usercode or an asterisk (*).

The data images must be of the type specified at the start of the global data

specification. The types of global data specifications are defined as follows:

Data Type Meaning

DATA Allows any characters in the EBCDIC character set.

EBCDIC A synonym for DATA.

The data images should begin on the line or card image following the global data

specification heading.

Note: Any data following the heading on the same line is ignored.

Tasks are read from the global data specification as if they were an input file, and each

line of data images is treated as a new record of the input file. A record in a disk file

created by CANDE with a FILEKIND=JOBSYMBOL contains data in columns 1 through

80, spaces in columns 81 and 82, and the sequence number in columns 83 through 90.

Since the default MAXRECSIZE that a program uses when reading these data images is

14 words (84 characters), care must be taken to ensure that unwanted characters are not

included in the data.

Note: To ensure that no unwanted information is read from columns 81 through 84 of

the data images, equate UNITS to CHARACTERS and MAXRECSIZE to 80.

The construct that terminates the global data specification also separates the data

specification from the next declaration or statement; it is not necessary to follow the data

specification with a semicolon (;).

Global Data Specifications

4–14 8600 1047–506

For a global data specification to be used by a task, the task initiation statement should

contain a file equation equating the TITLE file attribute to the file name constant specified

in the global data specification. The file equation should also equate the KIND attribute of

the file to READER.

When more than one task uses the same global data specification as input, each task

begins reading at the start of the deck. WFL also enables you to use local data

specifications, which provide input for a single task only. Refer to “Local Data

Specifications” in Section 5 for a further description of this capability.

A global data specification can appear only in jobs stored in disk files and initiated by a

START statement, or in jobs submitted through card readers.

Note: Global data specifications can occur only in the outer block of a job; that is, they

cannot be declared in subroutines.

Example

The following job uses a global data specification:

?BEGIN JOB SURF/METER;

DATA WAVE/HEIGHTS % Begin global data specification

3.5

1.2

23.4

? % End global data specification

RUN (WALLY)SURF/ANALYZE;

FILE WAVEIN(TITLE=WAVE/HEIGHTS,KIND=READER);

RUN (WALLY)SURF/REPORT;

FILE WAVES(TITLE=WAVE/HEIGHTS,KIND=READER);

?END JOB.

8600 1047–506 5–1

Section 5

Task Initiation

Overview

A task is a process that runs in its own stack. This section discusses the various task

initiation statements, task attribute assignments, file equations, task variables, and the

use of local data specifications to provide input to a task.

Task Initiation Statements

Explanation

The following table lists all the WFL statements that initiate tasks. For more information

about a particular statement, refer to Section 6, “Statements.”

Statement Effect

ADD Copies files that are not already resident on the destination.

ARCHIVE Archives files according to the archive task selected.

Include one of the following words to complete the archive

statement, as in ARCHIVE FULL:

• DIFFERENTIAL

• FULL

• INCREMENTAL

• MERGE

• RESTORE

• RESTOREADD

• ROLLOUT

BIND Combines object code files.

COMPILE Compiles a program.

COPY Copies files.

LOG Runs the LOGANALYZER utility, which reports on selected records

in the system log.

PB Runs the SYSTEM/BACKUP utility.

PTD Submits a peripheral testing routine.

Task Initiation Statements

5–2 8600 1047–506

Statement Effect

RUN Executes a program.

START Initiates a job stored in a disk file.

Each task initiation statement normally executes synchronously; that is, the job waits for

completion of the task before continuing to the next statement in the job. Certain tasks

can be made to run asynchronously by preceding the task initiation statement with the

word PROCESS. An asynchronous task executes concurrently with the job. Refer to the

PROCESS statement syntax in Section 6 for a complete list of statements that can be

processed asynchronously.

A subroutine invocation statement normally does not initiate a task. However, an

asynchronous task can be initiated by a subroutine invocation statement that occurs

within a PROCESS statement.

The START statement differs from the other task initiation statements in an important

way. The START statement both compiles and executes a job. The compile is executed

synchronously with the job that contains the START statement, but the execution occurs

asynchronously and is not associated with the original job. A PROCESS START also

causes the compilation to occur asynchronously from the originating job.

Example

The following example illustrates the difference between synchronous and asynchronous

task initiation:

COMPILE PROG/F1 WITH COBOL85 LIBRARY;

COBOL85 FILE CARD = PROG/SOURCE ON DISK;

PROCESS COPY & COMPARE PROG/F1 TO PROGTAPE;

RUN PROG/F1;

The statements in this example compile a program, and then copy it onto tape while the

program is executing.

The COMPILE statement initiates a synchronous task of compiling the program. When

the compilation is finished, the COPY statement starts an asynchronous process of

copying the new code file to tape. As soon as the copy process starts, the RUN

statement initiates the synchronous process of executing the new program. The second

line of the COMPILE statement contains a file equation, however each of these task

initiation statements can be followed by a task variable and by task equations.

The remainder of this section is devoted to explaining the common features that enable

you to control the manner in which tasks are executed.

Task Equation

8600 1047–506 5–3

Task Equation

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ ; ÄÂÄ<task attribute assignment>ÄÂÄÁÄÙ

ÃÄ<file equation>ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<library equation>ÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<database equation>ÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ ; ÄÁÄ<local data specification>ÄÁÄÙ

Explanation

The preceding syntax represents a task equation that can be used with the RUN, LOG,

PB, or PTD statements.

Task attribute assignment, file equation, library equation, database equation, and local

data specification are all defined later in this section.

The syntax for task equations with a COMPILE or BIND statement is set up to enable

task equations to be applied either to the compilation itself or to the resulting object code

file. Refer to the COMPILE or BIND statement in Section 6, “Statements,” for more

information.

The COPY or ADD statement enables the use of task attribute assignments, but does

not enable the use of file equations, database equations, or local data specifications.

Refer to the COPY or ADD statement in Section 6, “Statements.”

The only task equation permitted by the START statement is the STARTTIME

specification. Refer to the START statement in Section 6, “Statements.”

A task equation list can be specified for a subroutine invocation statement only when it

occurs within a PROCESS statement. Refer to the subroutine invocation statement in

Section 6, “Statements.”

Task Attributes

5–4 8600 1047–506

Task Attributes

Task attributes describe and control many aspects of process execution. They apply not

only to tasks but also to jobs. The same set of task attributes can be used to describe all

processes.

The values of the task attributes can be set or interrogated, thus enabling a process to

monitor and control the execution of another process or itself. Task attributes are

accessed with task variables. Task variables are explicitly declared in a job, and are

associated with a particular task by a task initiation statement.

Two predeclared task variables are provided: MYSELF, which accesses the attributes of

the task itself, and MYJOB, which accesses the attributes of the job. These are

described in “MYJOB and MYSELF Predeclared Task Variables” later in this section.

Table 5–1 lists the task attributes that are available through WFL, with the task attributes

grouped together into several functional categories. Task attributes with a type of task or

event are not available through WFL, and thus do not appear in the table.

More detailed information on task attributes and their use, including descriptions of all

the task attributes, can be found in the Task Attributes Reference Manual.

Table 5–1. Task Attribute Groupings

Task Task Attribute WFL Type

Billing CHARGE

USERCODE

Host Services

Tasking

HOSTNAME

ITINERARY

Note: The form of the

<name> construct that allows

17 EBCDIC characters other

than quotation marks (") is not

supported.

Data Comm AUTOSWITCHTOMARC

DESTSTATION

DISPLAYONLYTOMCS

LANGUAGE

ORGUNIT

SOURCEKIND

SOURCESTATION

STATION

STATIONNAME

TANKING

Task Attributes

8600 1047–506 5–5

Table 5–1. Task Attribute Groupings

Task Task Attribute WFL Type

Debugging OPTION

TADS

TASKFILE

Files CURRENTDIRECTORY

DATABASE

FAMILY

FILE

FILEACCESSRULE

OPTION

Notes:

• FILECARDS is an

acceptable synonym for

FILE.

• The AUTORM option is

the only option of this

attribute that affects disk

files.

Identification JOBNUMBER

MIXNUMBER

NAME

Interprocess

Communication

LOCKED

PARTNEREXISTS

STATUS

SW1 through SW8

TARGET

TASKLIMIT

TASKSTRING

TASKVALUE

TYPE

integer task attribute>

Task Attributes

5–6 8600 1047–506

Table 5–1. Task Attribute Groupings

Task Task Attribute WFL Type

Job Summaries JOBSUMMARY

JOBSUMMARYTITLE

NOJOBSUMMARYIO

OPTION

Note: The NOSUMMARY

option is the only option of

this attribute that affects job

summaries.

<option assignment

Libraries LIBRARY

LIBRARYSTATE

LIBRARYUSERS

Memory

Management

CORE

STACKLIMIT

STACKSIZE

Note: STACK is an

acceptable synonym for

STACKSIZE.

Print Output BACKUPFAMILY

BDNAME

DESTSTATION

OPTION

PRINTDEFAULTS

TASKFILE

Note: The BACKUP,

BDBASE, TODISK, and

TOPRINTER options are the

only options that affect printer

output.

Resource

Usage Data

ACCUMIOTIME

ACCUMPROCTIME

ELAPSEDTIME

INITPBITCOUNT

INITPBITTIME

OTHERPBITCOUNT

OTHERPBITTIME

TEMPFILEMBYTES

Task Attributes

8600 1047–506 5–7

Table 5–1. Task Attribute Groupings

Task Task Attribute WFL Type

Resource

Usage Limits

ELAPSEDLIMIT

MAXIOTIME

MAXLINES

MAXPROCTIME

MAXWAIT

PRIORITY

RESOURCE

SAVEMEMORYLIMIT

STACKLIMIT

TASKLIMIT

TEMPFILELIMIT

WAITLIMIT

Restarting

Tasks

BRCLASS

CHECKPOINTABLE

RESTART

RESTARTED

Security ACCESSCODE

FILEACCESSRULE

USERCODE

DECKGROUPNO

Task History ERROR

HISTORY

HISTORYCAUSE

HISTORYTYPE

HSPARAMSIZE

OPTION

STACKHISTORY

STATUS

STOPPOINT

SUPPRESSWARNING

TASKWARNINGS

Task Attribute Assignment

5–8 8600 1047–506

Task Attribute Assignment

ÄÄÂÄ<Boolean task attribute>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄ´

ÃÄ<file name task attribute>ÄÄ = ÄÄ<file name>ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<integer task attribute>ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄ´

ÃÄ<mnemonic task attribute>ÄÄ = ÄÄ<task mnemonic primary>Ä´

ÃÄ<name task attribute>ÄÄ = ÄÄ<name>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<real task attribute>ÄÄ = ÄÄ<real expression>ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<string task attribute>ÄÄ = ÄÄ<string expression>ÄÄÄÄÄÄÄ´

ÃÄ<title task attribute>ÄÄ = ÄÄ<file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<complex task attribute assignment>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

Task attributes are used to monitor and control the execution of tasks. For details on the

meanings and uses of task attributes, refer to the Task Attributes Reference Manual.

Task attribute assignments, in general, follow this format:

Each attribute accepts only a particular type of value: Boolean, or integer, for example. In

most cases, WFL enables variables and expressions to be used for the attribute value.

Task attribute assignments can be used in job attribute lists, task declarations, task

assignment statements, and task equation lists. Certain restrictions apply to task

attribute assignments that occur in task declarations. Refer to “Task Variables” in

Section 4 for more information.

Any task attributes that are not explicitly assigned values in the WFL job receive default

values when the task is initiated. These default values come from the following sources:

• If task attribute values are assigned to an object code file when it is originally

compiled, these become the default values whenever that object code file is

executed. The task attributes compiled into an object code file can later be

permanently changed with the MODIFY statement, without recompiling the source

file.

• Certain task attributes inherit values from the attributes of the job. For example, the

USERCODE attribute receives the value of the USERCODE attribute of the job. To

determine whether a particular attribute is inherited in this way, refer to the

appropriate attribute description in the Task Attributes Reference Manual.

• Each attribute has a particular default value that is used if it is not overridden by any

of the previously mentioned causes. Defaults vary from one attribute to another.

If a particular task attribute is assigned values more than once in a given job attribute list,

task declaration, task assignment statement, or task equation list, then the last value

specified for the task attribute overrides the previous ones.

Task Attribute Assignment

8600 1047–506 5–9

The complex task attribute assignments are assignments to task attributes that require a

fairly complex value. The syntax for each of these attribute assignments appears in

“Complex Task Attribute Assignments” later in this section.

The syntax for the various kinds of expressions referred to in the <task attribute

assignment> syntax diagram is given in Section 7, “Expressions.” The following pages

describe the syntax used in WFL for assigning values to the various kinds of task

attributes.

Examples

Boolean Assignment

If a Boolean-valued attribute occurs in a task attribute assignment without any value

specified for it, it is assigned TRUE. Thus, the following two examples are equivalent:

RUN OBJECT/NATTY; RUN OBJECT/NATTY;

LOCKED; LOCKED = TRUE;

TADS; TADS = TRUE;

A Boolean attribute can also be assigned the result of various comparisons, as in the

following example:

RUN OBJECT/KAYA;

SW1 = X GEQ Y; % Arithmetic comparison

SW2 = STRING1 EQL STRING2; % String comparison

SW3 = INFILE (SECURITY) IS PUBLIC; % File mnemonic comparison

SW4 = TVAR(HISTORYCAUSE)

IS OPERATORCAUSEV; % Task mnemonic comparison

SW5 = B1 OR B2; % Boolean expression

Integer Assignment

The following are examples of integer attribute assignments:

PRIORITY = 50; % Assigns an integer constant.

CLASS = X; % Assigns an integer variable.

MAXPROCTIME = Y + Z; % Assigns the value of an integer

% expression.

The value can also be taken from a task variable defined earlier in the program, if a task

variable was associated with that task:

PRIORITY = TVAR1 (PRIORITY);

Task Attribute Assignment

5–10 8600 1047–506

Mnemonic Assignment

Mnemonic attribute values can be assigned in one of the following ways.

• From a direct assignment:

RUN (WENDY)OBJECT/LPFINDER;

FILEACCESSRULE = DEFAULT;

• From a previously defined task variable:

TASKA (FILEACCESSRULE = DECLARER);

RUN (WENDY)OBJECT/LPFINDER;

FILEACCESSRULE = TASKA (VISIBILITY);

• From a string value:

RUN (WENDY)OBJECT/LPFINDER;

FILEACCESSRULE = #STVAR1; % STVAR1 is a string variable.

Real Assignment

The following are examples of real attribute assignments:

MAXIOTIME = DECIMAL(STR1); % STR1 is a string variable.

MAXPROCTIME = X; % X is a real variable.

Title Assignment

A title-valued attribute accepts a value that follows the syntax of a file title. This is shown

in the following example:

JOBSUMMARYTITLE = (WALLY)NUMB/CALC ON SHIPPK;

String expressions can also be used in a title assignment:

MYJOB(JOBSUMMARYTITLE = (#STR1)#STR2/#STR3); % Where STR1, STR2, and STR3

% are string variables.

MYJOB(JOBSUMMARYTITLE = #STR4); % Where STR4 contains a

% valid file title.

Complex Task Attribute Assignments

8600 1047–506 5–11

Complex Task Attribute Assignments

ÄÄÂÄ <accesscode assignment> ÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <core assignment> ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <currentdirectory assignment> Ä´

ÃÄ <family assignment> ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <option assignment> ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <printdefaults assignment> ÄÄÄÄ´

ÃÄ <resource assignment> ÄÄÄÄÄÄÄÄÄ´

ÃÄ <suppresswarning assignment> ÄÄ´

ÀÄ <usercode assignment> ÄÄÄÄÄÄÄÄÄÙ

Explanation

The complex task attribute assignments are assignments to attributes that require

complex or unusual values. The syntax for these assignments is discussed in the

following pages. The uses of these attributes are described in the Task Attributes

Reference Manual.

Complex Task Attribute Assignments

5–12 8600 1047–506

ACCESSCODE Assignment

ÄÄ ACCESSCODE ÄÄ = ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄ <accesscode> ÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ´

ÃÄ # ÄÄ <string primary> ÄÙ ÀÄ / ÄÂÄ <password> ÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ # ÄÄ <string primary> Ä´

ÀÄ # ÄÄ <string primary> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄ <name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The ACCESSCODE attribute assigns an accesscode to a task.

The following is an ACCESSCODE assignment:

ACCESSCODE = CHARLY/V5;

For an explanation of string primaries, refer to “Using String Primaries” in Section 8 of

this manual.

To change the password of a job, you must use the ACCESS statement. Refer to

Section 6, “Statements,” for details.

A password-aging feature is available through the InfoGuard Password Management

facility. When the accesscode password-aging feature is enabled, the WFL compiler

gives a warning if the accesscode password specified for a job is in the warning state. An

error is given if the password has expired. Refer to the Security Features Guide for

details.

Examples

The following example assigns a string variable that has the accesscode and password

as its value:

ACCESSCODE = #ACCSTR;

The following example assigns separate string variables as values for the accesscode

and password:

ACCESSCODE = #ACCSTR / #ACCPASTR ;

Complex Task Attribute Assignments

8600 1047–506 5–13

CORE Assignment

ÄÄ CORE ÄÄ = ÄÂÄ <total core> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ( ÄÄ <data core> ÄÄ , ÄÄ <code core> ÄÄ ) ÄÙ

ÄÄ <integer expression> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The CORE attribute provides an estimate of memory required to schedule a task.

Examples

The following example assigns an integer constant as the total core value:

CORE = 50;

The following example assigns the total core value of the product of X and Y, which are

integer variables assigned earlier in the job:

CORE = (X * Y);

The following example assigns data core the sum of W and X, and assigns code core the

difference of Y and Z. The letters W, X, Y, and Z are previously defined integer variables.

CORE = (W + X, Y - Z)

Complex Task Attribute Assignments

5–14 8600 1047–506

CURRENTDIRECTORY Assignment

ÄÄ CURRENTDIRECTORY ÄÄ = ÄÂÄ <absolute pathname ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <relative pathname ÄÙ

Refer to the Task Attributes Reference Manual for the definition of absolute and relative

path names.

Explanation

The CURRENTDIRECTORY attribute specifies the directory that is the starting point for

resolution of relative path names. It contains a character string, in path name format,

which is prefixed to a file name during such operations as opening or searching for a file

when the file name is relative and the SEARCHRULE attribute of the file is POSIX.

If the string that assigns the CURRENTDIRECTORY attribute represents a relative path

name, the string is prefixed by the current value of the attribute, and the attribute is set

from the combined string. Setting the CURRENTDIRECTORY attribute to a relative path

name is permitted only on an active task and only by the associated process.

If the CURRENTDIRECTORY attribute is not explicitly specified on the task variable or

code file, the attribute is inherited from the parent task if the parent task’s

CURRENTDIRECTORY attribute is set. Otherwise, the attribute defaults to a null string.

If a WFL job contains a USERCODE assignment in the job header, but does not contain a

CURRENTDIRECTORY assignment, the job’s CURRENTDIRECTORY attribute is set to

the POSIXINITDIR (POSIX Initial Directory) value from the USERDATAFILE.

Examples

The CURRENTDIRECTORY of the job is set from the USERDATAFILE. PROG1 runs with

the value. PROG2 runs with a value of "/-/NEWFAM/USERCODE/MYUC/DIR1", which

references the directory (MYUC)DIR1 ON NEWFAM.

BEGIN JOB;

USER=MYUC/MYPW;

RUN PROG1;

RUN PROG2; CURRENTDIRECTORY="/-/NEWFAM/USERCODE/MYUC/DIR1";

END JOB.

In the following example, PROG3 runs with a CURRENTDIRECTORY value of "/A/B/C",

which references the directory *A/B/C on the family specified as the root family by the

DL ROOT command:

BEGIN JOB;

CURRENTDIRECTORY="/A/B";

MYSELF(CURRENTDIRECTORY="C");

RUN PROG3;

END JOB.

Complex Task Attribute Assignments

8600 1047–506 5–15

FAMILY Assignment

<family assignment>family

ÄÄ FAMILY ÄÂÄ<family specification>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ = ÄÄ<task identifier>ÄÄ ( ÄÄ FAMILY ÄÄ ) Ä´

ÃÄÄÄÄÄÂÄ<string expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÀÄ # ÄÙ

ÄÄ <target family name> ÄÄ = ÄÄ <primary family name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄ ONLY ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ OTHERWISE ÄÄ <alternate family name> ÄÙ

ÄÄ <family name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The FAMILY attribute determines the families that the task will use when creating files or

searching for files.

String expressions and string primaries that evaluate to constants can be used for

FAMILY in the WFL job heading. WFL job parameters can be used in constant

expressions.

Examples

The following is an example of a FAMILY assignment:

FAMILY DISK = DISK OTHERWISE MYPACK;

Note: Most WFL statements can locate a file residing on either the primary family or

the alternate family. However, the ADD, ALTER, ARCHIVE, CATALOG, CHANGE, COPY,

MODIFY, MOVE, REMOVE, and SECURITY statements do not search the alternate

family.

The following FAMILY assignment uses a previously defined string variable named

FAMSTRING:

FAMSTRING := "DISK = DISK ONLY";

RUN OBJECT/FUGUE;

FAMILY = #FAMSTRING1;

Complex Task Attribute Assignments

5–16 8600 1047–506

The following FAMILY assignment uses a string expression. STR1 and STR2 are string

variables that were assigned values earlier in the job:

FAMILY = #("DISK = " & STR1 & " OTHERWISE " & STR2);

The following example assigns a task the family specification associated with the task

variable named TASKVAR1. The task variable can receive a FAMILY assignment when it

is declared, or it can inherit a FAMILY assignment from the task to which it was most

recently assigned.

FAMILY = TASKVAR1 (FAMILY);

The FAMILY assignment is unique in that it does not require a number sign (#) before the

expression <task identifier> (<attribute name>). Similar expressions, when used for

other attributes, do require the number sign.

Complex Task Attribute Assignments

8600 1047–506 5–17

OPTION Assignment

ÄÄ OPTIONS ÄÄ = ÄÂÄ # ÄÄ <string primary> ÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ ( ÄÁÄÂÄ ARRAYS ÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ) ÄÙ

ÃÄ AUTORM ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ BACKUP ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ BASE ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ BDBASE ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ CODE ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ CRITICALBLOCK ÄÄÄÄ´

ÃÄ DBS ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ DEBUG ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ DSED ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ FAULT ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ FILES ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ LIBRARIES ÄÄÄÄÄÄÄÄ´

ÃÄ LONG ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ NOSUMMARY ÄÄÄÄÄÄÄÄ´

ÃÄ PRIVATELIBRARIES Ä´

ÃÄ SORTLIMITS ÄÄÄÄÄÄÄ´

ÃÄ TODISK ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ TOPRINTER ÄÄÄÄÄÄÄÄ´

ÀÄ * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

The OPTION attribute sets options for the task. The options for the task affect program

dumps, job summary printing, backup-file handling, and other areas. The options of the

OPTION attribute are explained in the Task Attributes Reference Manual under the

discussion of the OPTION attribute.

If an asterisk (*) is included in the OPTION assignment, then any options provided by a

previous assignment are to be merged with the options specified by this assignment. If

an asterisk is not included, then any options specified by a previous assignment are not

retained when this assignment occurs.

The asterisk option is particularly useful when assigning options to an object code file as

defaults, because it enables additional options to be specified at run time without causing

the default options being overwritten.

Complex Task Attribute Assignments

5–18 8600 1047–506

Examples

The following example illustrates the use of the asterisk option:

COMPILE OBJECT/X WITH COBOL85 LIBRARY; % Compiles source file X and

COMPILER FILE CARD (TITLE=X,KIND=DISK); % saves object code file

OPTION=(FAULT); % OBJECT/X with FAULT option

. % as default

RUN OBJECT/X; % OBJECT/X runs with OPTION = (FAULT)

RUN OBJECT/X; % OBJECT/X runs with OPTION = (FAULT,

OPTION = (*,ARRAYS,FILES); % ARRAYS,FILES)

The # <string primary> syntax enables string variables and expressions to be used to

assign the option values. The parentheses around the option values can be omitted when

this form of the syntax is used. The following job excerpt illustrates a use of this syntax.

STRING S; % Declares string variable S.

S:="LONG,FAULT"; % Assigns option values to S.

RUN OBJECT/WELLCOMP; % Runs the program with the options

OPTION=#S; % LONG and FAULT set.

The parentheses before and after the option list are optional when the option assignment

occurs in a task equation list, job attribute list, or compiler task equation list. However,

the parentheses are required if the OPTION assignment occurs in a task declaration or

task assignment statement. The following example illustrates OPTION assignments in

each of these contexts:

?BEGIN JOB;

OPTION = NOSUMMARY, BASE; % job attribute list

TASK TVAR (OPTION=(ARRAY,AUTORM),

MAXPROCTIME=73); % task declaration

COMPILE OBJECT/X WITH ALGOL LIBRARY;

COMPILER FILE CARD (TITLE = X);

ALGOL OPTION = ARRAY, DSED; % compiler task equation list

RUN OBJECT/Z;

OPTION = LONG, FAULT; % task equation list

TVAR (OPTION=(BACKUP),PRIORITY=50); % task assignment statement

?END JOB.

Complex Task Attribute Assignments

8600 1047–506 5–19

PRINTDEFAULTS Assignment

ÄÄ PRINTDEFAULTS ÄÄ = ÄÄ ( ÄÄ <printdefaults assignment list> ÄÄ ) ÄÄÄÄ´

Explanation

The PRINTDEFAULTS attribute enables you to provide a different set of default values (in

place of the system default values) for the print modifiers or print-related file attributes

that control the creation, routing, and formatting of backup files. If the PRINTDEFAULTS

attribute is set for a task, the default values specified are applied to all PRINT statements

and any printer backup files created by the task.

The print attribute phrases and print modifier phrases that appear in the printdefaults

assignment list are merged into the current print defaults. The print modifier and print

attribute forms reestablish the system default value for that print modifier or print-related

file attribute. Refer to the PRINT statement in Section 6, “Statements,” for the syntax of

the <printdefaults assignment list>, and for more information about print modifiers and

print-related file attributes.

The PRINTDEFAULTS attribute can be included in the USERDATAFILE associated with

each usercode. For further information, see MAKEUSER in the Security Administration

Guide.

Examples

To establish print default values for a job, use a task assignment statement such as the

following:

MYJOB (PRINTDEFAULTS=(DOUBLESPACE=TRUE,AFTER="20:00"));

The default values established for the job are inherited by any tasks initiated by the job.

The defaults for the job can be varied for different parts of the job by using several task

assignment statements. To establish default values for a task, you can assign values

directly to the PRINTDEFAULTS attribute of a task, as in the following example:

RUN (SANTA)GIFT/LIST;

PRINTDEFAULTS=(DESTINATION="LP14",SAVEBACKUPFILE=TRUE);

The assigned values override the default values that the task would otherwise inherit

from the job.

Complex Task Attribute Assignments

5–20 8600 1047–506

Each file declaration in a task can override the default file attributes and print modifier

values assigned to that task. The attribute values specified in a file declaration in the task

can, in turn, be overridden through the file equation. File equations can be used to assign

file attributes to files used by a task.

For example, if a program named OBJECT/BOG prints a file called OUTFILE, the

following example would modify the way the file is printed:

RUN OBJECT/BOG;

FILE OUTFILE (SAVEBACKUPFILE=TRUE,PRINTCOPIES=3,AFTER="23:00");

Print modifiers cannot be specified in file equations; they can only be included in PRINT

statements or PRINTDEFAULTS assignments.

Complex Task Attribute Assignments

8600 1047–506 5–21

RESOURCE Assignment

ÄÄ RESOURCE ÄÄ = ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄ ( ÄÄ TAPE ÄÄ = ÄÄ <integer constant expression> ÄÄ ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The RESOURCE attribute specifies how many tape units are needed by a task.

Example

The following example assigns values to the RESOURCE attribute:

?BEGIN JOB ATTRBTEST(INTEGER PARAM);

RUN (RAJA)OBJECT/WEATHER/FORECAST;

RESOURCE = (TAPE = PARAM);

?END JOB.

This resource assignment indicates that the program requires the number of TAPE drives

passed to the job in the parameter PARAM. Job parameters, such as PARAM in the

previous example, can be used in the RESOURCE assignment because they are constant

identifiers rather than variables.

Note: The integer constant expression must be an integer in the range of 0 to 255

when it is completely evaluated.

Complex Task Attribute Assignments

5–22 8600 1047–506

SUPPRESSWARNING Assignment

ÄÄ SUPPRESSWARNING ÄÄ = ÄÄ <suppresswarning list> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄÂÄ ALL ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ´

ÃÄ NONE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÃÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ <warning number> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÙ

ÀÄ <hyphen> ÄÙ ÀÄ <hyphen> ÄÄ <warning number> ÄÙ

An unsigned integer in the range of 1 through 29999.

Explanation

The SUPPRESSWARNING attribute suppresses run-time warning messages for a

process. Most of these messages are warnings that indicate the process has just used a

feature that is scheduled for deimplementation on a future release.

You can suppress specific run-time warning messages by assigning a set of warning

numbers or warning number ranges to the SUPPRESSWARNING attribute. Each warning

number corresponds to a particular run-time warning message. If the

SUPPRESSWARNING list begins with a hyphen (-), the hyphen is interpreted as a minus

sign and the warning numbers following the hyphen are deleted from the previously

created SUPPRESSWARNING list.

Refer to the Task Attributes Reference Manual for additional information regarding the

SUPPRESSWARNING task attribute.

Examples

The following is a simple SUPPRESSWARNING assignment that causes all run-time

warning messages to be suppressed:

SUPPRESSWARNING = "ALL";

The following assignment suppresses the run-time warning messages that are in the

ranges 1 through 25, 32 through 45, and 100 through 199:

SUPPRESSWARNING = "1-25,32-45,100-199";

The following assignment deletes messages 10 through 20 from the

SUPPRESSWARNING list that was created in the previous example:

SUPPRESSWARNING = "-10-20";

Complex Task Attribute Assignments

8600 1047–506 5–23

USERCODE Assignment

ÄÄ USERCODE ÄÄ = ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄ <usercode> ÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ´

ÃÄ # ÄÄ <string primary> ÄÙ ÀÄ / ÄÂÄ <password> ÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ # ÄÄ <string primary> Ä´

ÀÄ # ÄÄ <string primary> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

The USERCODE attribute assigns a usercode and its associated privileges to a task. The

password must be included if the usercode has a password associated with it.

For an explanation of string primaries, refer to “Using String Primaries” in Section 8 of

this manual.

A password-aging feature is available through the InfoGuard Password Management

facility. If the password-aging feature is enabled, the WFL compiler gives a warning if the

usercode password specified for the job is in the warning state. An error is given if the

password has expired. The password-aging feature is discussed further in the Security

Features Guide.

The USER statement changes the usercode of the job or processed subroutine. The

password associated with the usercode of the job can be changed with the PASSWORD

statement. These statements are described later in Section 6, “Statements.”

Examples

The following is a simple USERCODE assignment:

USERCODE = WALLY/BEAR;

The following example uses a string expression:

USERCODE = #(USER1/PASS1);

The following example takes the usercode value from a task variable:

TASK TASKVAR (USERCODE = RAJA/RANI); % Task variable declaration

RUN (WALLY)OBJECT/ALPHA; % Run statement with

USERCODE = #TASKVAR(USERCODE) / RANI; % usercode specification

Note: A string task attribute primary (such as #TASKVAR(USERCODE), in the preceding

example) gives the value of a usercode, but not its associated password. In this example,

the password is given separately in the second USERCODE assignment.

Using Task Variables

5–24 8600 1047–506

Using Task Variables

Explanation

Task variables are variables that can be associated with particular tasks. The means of

defining them are given under “Task Variables” in Section 4. Task variables are used for

two basic purposes: as a means of assigning task attributes or file equations to a task,

and as a means of inquiring about the attributes of a task.

Any number of task variables can be declared and used in a job. Also, a particular task

variable can be associated with more than one task in the course of a job. However, a

task variable can only be attached to one task at any given time and cannot be reused

until that task has terminated. Care should be taken when reassigning a task variable that

was associated with an asynchronous task.

Examples

For example, the following statement is permissible:

RUN X [T];

INITIALIZE (T);

COPY A AS B [T];

However, a run-time error results from the following:

PROCESS COMPILE X WITH ALGOL LIBRARY [T];

RUN Y [T];

If a task variable is not associated with an asynchronous task, the WFL compiler will

allocate a task variable internally and associate it with the task.

Note that a run-time error will result if the PROCESS statement, which initiates tasks

asynchronously, is executed in either of the following ways:

• Repeatedly with the same task variable, while the previously processed task is still

active.

• In a loop (one that uses the DO or WHILE statement, for example) with no task

variable, while the previously processed task is still active. The error occurs because

the internal task variable is associated with more than one task at the same time.

Using Task Variables

8600 1047–506 5–25

Assigning Task Attributes

When a task variable is associated with a task, any task attribute assignments or file

equations currently assigned to that task variable are assigned to the task.

If a task variable is to be used to assign task or file attribute values to a task, these

values can be specified in the task declaration that declares that task variable. (Refer to

Section 4, “Declarations,” for the syntax of a task declaration.)

The attribute values associated with the task variable can be added to or changed in any

of the following ways:

• Task assignment statements can be used to associate additional task attribute

assignments and file equations with the task variable, or to override values that had

been specified for that task variable previously. (Refer to the assignment statement

in Section 6, “Statements,” for a description of the task assignment statement.)

• Task attribute assignments in a task assignment statement can be applied in any

order, not necessarily in the order listed. If the order is important, the task

assignments should be put into separate task assignment statements. Thus, a

statement such as the following is undesirable:

TVAR(STATUS=NEVERUSED,FAMILY DISK = PARTS ONLY);

The FAMILY assignment in this example can be executed before the STATUS

assignment. If it is, the FAMILY value will be discarded.

• When the task variable is used in a task initiation statement, and attribute

assignments follow the task initiation statement, they are added to the values that

are currently assigned to the task variable. Where there is a conflict, the values

following the task initiation statement override those currently associated with the

task variable.

• When the task variable is used in a task initiation statement, and the task is a

program, any attribute assignments associated with the object code file of the

program are added to those currently associated with the task variable. Where there

is a conflict, the values currently associated with the task variable override those

associated with the object code file.

• If, at any point in the job, the INITIALIZE statement is used to reinitialize the task

variable, then all task and file attributes previously associated with the task variable

are discarded. For example, the following statement will reinitialize the task variable

TVAR:

INITIALIZE (TVAR);

Using Task Variables

5–26 8600 1047–506

Examples

In the following example, the program (RAJA)OBJECT/ALT runs with the task and file

attributes given for the task variable TVAR in the task declaration:

?BEGIN JOB;

TASK TVAR (PRIORITY=50, % Task variable declaration

FILE INFILE (TITLE = F/T));

RUN (RAJA)OBJECT/ALT [TVAR]; % Task initiation statement

?END JOB.

The following example shows several ways in which a task variable can be assigned task

attribute values:

?BEGIN JOB ATTRIBUTES;

TASK T (PRIORITY=50,USERCODE=JAMES/PW, % Task declaration

FAMILY DISK = DISK ONLY);

RUN (PARTS)PROG [T]; % Task initiation

MAXPROCTIME = 90;

INITIALIZE (T); % Initialize statement

T (MAXPROCTIME=30); % Task assignment statement

RUN (PARTS)SUMMARY [T];

?END JOB.

Using Task Variables

8600 1047–506 5–27

Reusing Task Variables

When a task variable is to be reused for another task, the task variable should normally

be reinitialized first. Otherwise, the task variable retains the task attribute values that

were associated with the previous task, and these can sometimes cause undesirable

side effects.

Examples

The following examples show some of the possible side effects of reusing task variables

without reinitializing them.

The following example runs SYSTEM/CARDLINE twice:

?BEGIN JOB TASK/TEST;

TASK T;

RUN SYSTEM/CARDLINE[T];

FILE CARD (KIND=DISK,TITLE=INPUT1);

FILE LINE (KIND=DISK, PROTECTION=SAVE);

RUN SYSTEM/CARDLINE[T];

FILE CARD (KIND=DISK,TITLE=INPUT2);

?END JOB.

This program takes an input file named CARD and produces an output file named LINE,

which by default is a printer file.

The first time SYSTEM/CARDLINE is run, the file LINE is file-equated to have a KIND of

DISK, and the output is thus sent to a disk file. This file equation is also associated with

the task variable T. When SYSTEM/CARDLINE is run the second time, no file equation

for the file LINE is explicitly included, but the file equation is passed on by task variable T,

and the output is still sent to a disk file.

In the following example, T is the declared task used for two RUN statements. In the

second RUN statement, the PRIORITY information, file equation information, and setting

of the OPTION attribute are still in effect when Y is executed. When T is re-used, less

obvious side effects might also occur. For example, if X changes its TASKVALUE, that

TASKVALUE would still be in effect when Y is executed, which might cause undesirable

side effects on Y.

?BEGIN JOB EXAMPLE1;

TASK T;

T(PRIORITY=50);

RUN X[T];

FILE F(KIND=DISK);

T(OPTION=(FAULT));

RUN Y[T];

?END JOB.

Using Task Variables

5–28 8600 1047–506

The following example includes two COMPILE and GO statements that both have the

same task variable [T] associated with them. The task variable T has PRIORITY=50

assigned to it; this priority is applied to the GO part of both compiles.

File equations made to the first COMPILE statement also affect the second COMPILE

statement, because the task variable retains the file equations. Because of this fact, the

COMPILER FILE CARD equation after the first COMPILE statement has the (probably

unintentional) effect of causing the second COMPILE to also read from the disk file

named INPUT.

Both COMPILE statements are followed by file equations that affect the same file F; in

this case, the first COMPILE statement treats F as a disk file, and the second COMPILE

statement treats F as a remote file:

?BEGIN JOB EXAMPLE2;

TASK T;

T(PRIORITY=50);

COMPILE OBJECT/XDISK [T] WITH ALGOL GO;

COMPILER FILE CARD(KIND=DISK, TITLE=INPUT);

FILE F(KIND=DISK);

COMPILE OBJECT/XREM [T] WITH ALGOL GO;

FILE F(KIND=REMOTE);

?END JOB.

The following example illustrates how the INITIALIZE statement can be used to prevent

the attribute values of one task from being accidentally assigned to the next task:

?BEGIN JOB EXAMPLE3;

TASK T;

T(PRIORITY=50);

RUN X[T];

FILE F(KIND=DISK);

INITIALIZE(T);

T(OPTION=(FAULT));

RUN Y[T];

?END JOB.

The task variable T is reinitialized, after which the PRIORITY information and the previous

file equation information are no longer in effect. Thus, program Y runs with the FAULT

option set, but with no other task or file equations.

Using Task Variables

8600 1047–506 5–29

Interrogating Task Attributes

A very useful feature of task variables is that they enable you to inquire about the

attributes of a task after it is initiated. The syntax of expressions that use task variables

to return task attribute values is given in Section 7, “Expressions.” Table 5–2 lists the

expressions that are used to inquire about each type of task attribute.

Table 5–2. Expressions for Task Attribute Inquiry

Task Attribute Type Expression Used

<mnemonic task

attribute>

This expression is used for these attributes:

• ACCESSCODE

• OPTION

• FAMILY

• USERCODE

The following attributes cannot be interrogated:

• CORE

• PRINTDEFAULTS

• RESOURCE

Interrogating Task Status

5–30 8600 1047–506

Interrogating Task Status

The status or history of a task can be inquired about in either of two ways:

• By using a string task attribute primary to interrogate the value of the STATUS

attribute of the task.

Refer to the description of task mnemonic comparisons under “Boolean

Expressions” in Section 7 of this manual for an example. Refer to the description of

the STATUS attribute in the Task Attributes Reference Manual for a list of the

mnemonic values the attribute can have.

• By using the Boolean task state expression.

This is not actually a task attribute inquiry, but it does return information about a task.

Refer to “Task State” in Section 7.

Both of these inquiries return similar types of information about the task, but use

different mnemonic values to express the information.

File Attribute Inquiry

8600 1047–506 5–31

File Attribute Inquiry

The task variable cannot be used to interrogate the attributes of files used by a task.

Refer to “Interrogating File Attributes” later in this section for a discussion of how to

interrogate file attributes.

Interrogating Complex Task Attributes

The following points should be remembered when interrogating the values of complex

task attributes.

• Inquiries about the USERCODE attribute return the usercode only, without the

password.

• Inquiries about the ACCESSCODE attribute return the accesscode only, without the

accesscode password.

• Inquiries about the FAMILY attribute return a value with one of the following forms:

<target family name> = <primary family name> ONLY

<target family name> = <primary family name> OTHERWISE

"" % EMPTY STRING

• Inquiries about the OPTION attribute return a string value that is a list of all the

options that are set, separated by commas (,). The options can be listed in any order.

Thus, the expression STR := TVAR(OPTION); could return any of the following

values, among others:

"ARRAYS, FILES, LONG"

"CODE"

"CODE, BDBASE, AUTORM, LONG"

Example

The following is an example of an expression that can be used to extract the primary

family name from the FAMILY attribute:

IF LENGTH(MYSELF(FAMILY)) GTR 0 THEN

MYFAMILY := HEAD(DROP(TAIL(MYSELF(FAMILY),NOT "="),

2),NOT " ");

ELSE MYFAMILY := "DISK";

In this example, MYFAMILY is a string variable and MYSELF is the predefined task

variable. Any string variable or task variable could be used in their places. Refer to “String

Expressions” in Section 7 for explanations of the HEAD, DROP, and TAIL functions.

MYJOB and MYSELF Predeclared Task Variables

5–32 8600 1047–506

MYJOB and MYSELF Predeclared Task Variables

MYJOB and MYSELF are predeclared task variables that can be used to assign or

interrogate task attribute values. The MYJOB task variable is always assigned to the job

itself. If the MYJOB task variable is used in a task assignment statement, the values

specified for it are assigned to the job.

The syntax specified in Sections 5 and 7 that applies to declared task variables can be

used with the predeclared task variables MYJOB and MYSELF, except for the specific

cases documented under the section titled “Task State” in Section 7.

Examples

For example, the following statement assigns a value to the FAMILY attribute of the job:

MYJOB(FAMILY DISK = MYPACK ONLY);

Any task attributes you wish to specify for the job will normally be included at the start of

the job in the job attribute list. Thus, a task assignment statement using MYJOB is most

useful when you want to change the job attributes later in the job.

The following example uses MYJOB in a task attribute inquiry:

RUN SKYVAL; STATION = MYJOB(SOURCESTATION);

This example takes the value of the SOURCESTATION attribute of the job and assigns it

to the STATION attribute of a task.

The following statement assigns a value to the BDNAME attribute, so that backup files

are created under the directory MYBACKUPFILES:

MYJOB(BDNAME = MYBACKUPFILES);

BDNAME can also be reset by equating it to an empty string (or a string expression that

has the value of an empty string).

In an asynchronous subroutine, the MYSELF task variable is associated with that

subroutine; otherwise, it is assigned to the job and is synonymous with MYJOB. For

example, the following statement stores the value of the MIXNUMBER attribute of the

asynchronous subroutine or job in the variable I:

I := MYSELF(MIXNUMBER);

The following statement assigns the value 9 to the TASKVALUE attribute of the

asynchronous subroutine or job:

MYSELF(TASKVALUE = 9);

These predeclared task variables lose their special meaning if they are explicitly declared

in a job.

File Equations

8600 1047–506 5–33

File Equations

ÄÄ FILE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÄÄÂÄ<intname>ÄÄ = ÄÄ<file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÃÄ ( ÄÂÄÄÄÄÄÄÂÄÁÄ<file attribute assignment>ÄÁÄ ) Ä´

³ ÀÄ *, ÄÙ ³

ÀÄ<global file assignment>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄ <name constant> ÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ # ÄÄ <string primary> ÄÙ

Explanation

File equations can be used for any of the following reasons:

• To cause a task to read from or write to different files from those it normally would

• To change the attributes of files that a task reads from or writes to

• To cause a task to read from global data specifications or local data specifications

instead of from the input files the task would normally have used

File equations can appear in task equation lists, compiler task equation lists, task

declarations, and task assignment statements.

The intname used in a file equation should be the internal name used for a particular file

in the task to which the file equation is applied.

FILECARDS is an acceptable synonym for FILE.

File Equations

5–34 8600 1047–506

Causing the Task to Use a Different Input or Output File

The task can be made to use a different file than it would normally by file-equating the

TITLE attribute of the file. The simplest way to do this is by using the following syntax:

Examples

The following example illustrates the use of the <intname> = <file title>

RUN OBJECT/PROG;

FILE INFILE = (JACOB)INPUT/DATA ON ORDSPK;

This form of the file equation syntax changes the TITLE attribute of the file. When the

task tries to open the file that has the internal name INFILE, the file equation will cause it

to open the file (JACOB)INPUT/DATA ON ORDSPK.

The following is an example of alternate syntax for changing the TITLE attribute of a file:

RUN OBJECT/PROG;

FILE INFILE (TITLE = (JACOB)INPUT/DATA ON ORDSPK);

This syntax enables other attributes to be specified at the same time. For more

information, refer to “Assigning File Attributes” later in this section.

File Equations

8600 1047–506 5–35

Changing the Attributes of Files Used by the Task

Any or all of the attributes of a file used by a task can be assigned values in a file

equation.

When the program opens a file that has been file-equated, the attribute values specified

for that file in the WFL job are merged with those specified in the file declaration in the

program. If a file attribute is assigned a different value in the file equation than it is in the

file declaration in the program, then the value assigned in the file equation takes

precedence. If a file that is file-equated is not opened by the program, then the file

equation has no effect.

Certain combinations of file attribute assignments might not be legal; for example, the

value of the BLOCKSIZE attribute must be evenly divisible by the value of the

MAXRECSIZE attribute. Thus, a file equation that sets MAXRECSIZE to a value

incompatible with the BLOCKSIZE attribute would generate a run-time error.

In cases where a program uses a file that already exists (rather than creating one), any

file equations included for that file in the WFL jobs do not affect the physical file that the

program uses. Instead, such file equations alter the way the program reads from or

writes to the file.

For more information about file attributes, refer to the File Attributes Reference Manual.

Example

The following is an example of a file equation that assigns several attributes:

FILE INFILE (TITLE=(WALLY)OD/CON ON PARTS,KIND=DISK,MAXRECSIZE=12,

SECURITYTYPE=PUBLIC);

Causing the Task to Read from a Data Specification

For examples of file equations that cause a task to read from data specifications instead

of from its normal input files, refer to “Global Data Specifications” in Section 4 and to

“Local Data Specifications” later in this section.

How the Task Can Override WFL File Equations

It is possible for a task to override the WFL file equations that are assigned to it. WFL file

equations are merged only with those attributes specified in the file declaration in the

task. File attribute assignments made later in the task will override WFL file equations.

File Equations

5–36 8600 1047–506

Resolving Repeated File Equations to the Same File

When a given task equation list, compiler task equation list, task declaration, or task

assignment statement includes two or more file equations that apply to the same

internal file, the WFL compiler uses the following rules to decide which of the specified

file attribute assignments to use. These rules differ according to whether the intname

used is a name constant or a string primary.

If the intname used is a name constant, then the following rules apply:

• If a file equation includes an asterisk (*) before the file attribute assignments, then its

file attribute assignments are merged with any that have been specified for the file in

a previous file equation.

• If a file equation does not include the asterisk, all task attribute assignments

specified in previous file equations are discarded, and only the ones given in the

latest file equation are used.

If the intname used is a string primary, then the following rules apply:

• The file equation cannot contain an asterisk; if it does, a syntax error is given.

• If the string primary evaluates to the same internal file name as was specified in a

previous task equation, a run-time error is given.

Examples

In the following example, X1 is a name constant that specifies an intname. Because the

second file equation contains no asterisk, the first file equation is discarded, and the

values specified for the KIND and TITLE attributes are not used.

RUN (FOLKS)OBJECT/FREELOAD;

FILE X1(KIND=DISK,TITLE=TEST/X1);

FILE X1(MAXRECSIZE=20,UNITS=CHARACTERS);

In the following example, X1 is still a name constant that specifies an intname. However,

because the second file equation includes the asterisk, the attributes from both file

equations are merged:

RUN (FOLKS)OBJECT/FREELOAD;

FILE X1(KIND=DISK);

FILE X1(*,TITLE=TEST/X1);

Global File Assignment

8600 1047–506 5–37

Global File Assignment

ÄÄ <name constant> ÄÄ := ÄÄ <file identifier> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

A global file assignment is used to replace a file used by a program with a file declared in

the WFL job.

The name constant specified must be the internal name of the file used by the program.

The file identifier specified is the identifier that was used in the WFL file declaration.

Example

The following is an example of a global file assignment:

FILE INFILE1 := GLOB2;

The colon (:) before the equal sign (=) is important because if it were left out the

statement would be interpreted as a title assignment for the file rather than a global file

assignment.

The attribute values of the file that is assigned can be supplied in the file declaration or in

later file assignment statements; the system supplies default values for attributes that

are not explicitly assigned values in the job.

When a global file assignment replaces a file used by a program, all the attributes

associated with the original file are ignored. Therefore, if you want to alter only selected

attributes of a file used by a program, a global file assignment should not be used.

Instead, use the method described earlier in this section in “Changing the Attributes of

Files Used by the Task.”

Note: If a global file is used by a COBOL74 program and is used again in the same WFL

job, the COBOL74 program cannot close the global file with the LOCK phrase. However,

the global file can be closed with the SAVE phrase. The COBOL74 “CLOSE WITH LOCK”

statement is specifically implemented for the purposes of preventing access from within

the same program/run unit/job once the file has been closed.

Global file assignments make it possible to find out whether a task has changed any of

the attributes of a file. Refer to “Interrogating File Attributes” later in this section for

details.

You should be cautious about using global file assignments to cause more than one

program to use the same file. Refer to “Assigning File Attributes” later in this section for

details.

Using Remote Files

5–38 8600 1047–506

Using Remote Files

When a program needs to read from or write to a remote device attached to the system,

it opens a remote file and associates it with that device. A common example of this is a

program that sends data to or accepts input from the terminal where the program was

initiated. Special measures are required when using WFL to initiate a program that reads

from or writes to a remote file.

When a program tries to open a remote file, by default it tries to associate that file with

the station the program was initiated from. However, if the program was initiated by a

WFL job, then the program is not associated with a station, and an error is generated

when it attempts to open the remote file.

To prevent this problem, you can include the following statement near the start of the

WFL job, before any tasks are initiated:

MYJOB(STATIONNAME = #MYSELF(SOURCENAME));

This statement causes the STATIONNAME attribute of the WFL job to store the name of

the station that initiated the job. Any tasks of that job inherit the STATIONNAME value.

When any of these tasks opens a remote file, the remote file is linked by default to the

station that initiated the WFL job.

Before the STATIONNAME task attribute was implemented, the STATION task attribute

was the only method of specifying the default station for remote files. The STATION

attribute identifies a station by its logical station number (LSN). Use STATIONNAME

rather than STATION because the station name is stable, whereas the LSN is subject to

change.

The setting of the CANDE LAISSEZFILE option affects the ability of the program to open

remote files that are not directly associated with its own session. According to the value

of LAISSEZFILE, the task attribute assignment in the previous example might be

sufficient to enable the program to open the remote file, or the system might ask for an

OK from the station before the remote file is opened, or the program might be prohibited

from opening the remote file. Refer to remote files in the CANDE Configuration

Reference Manual for further information.

Another approach to dealing with programs that use remote files would be to file-equate

the remote files to a different KIND, such as DISK or READER.

File Attribute Assignment

8600 1047–506 5–39

File Attribute Assignment

ÄÄÂÄ <Boolean file attribute> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ <Boolean expression> ÄÄÄÄ´

ÃÄ <file name file attribute> ÄÄ = ÄÄ <file name> ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <integer file attribute> ÄÄ = ÄÄ <integer expression> ÄÄÄÄÄ´

ÃÄ <long file name file attribute> ÄÄ = ÄÄ <long file name> ÄÄ´

ÃÄ <long title file attribute> ÄÄ = ÄÄ <long file title> ÄÄÄÄÄ´

ÃÄ <mnemonic file attribute> ÄÄ = ÄÄ <file mnemonic primary> Ä´

ÃÄ <name file attribute> ÄÄ = ÄÄ <name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <real file attribute> ÄÄ = ÄÄ <real expression> ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <string file attribute> ÄÄ = ÄÄ <string expression> ÄÄÄÄÄÄÄ´

ÃÄ <title file attribute> ÄÄ = ÄÄ <file title> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <device kind assignment> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <serial number assignment> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

The file attribute assignment assigns values to the attributes of files referenced in a WFL

job. File attribute assignments can be used in file declarations, file assignment

statements, and file equations. Attribute values in file declarations must be constants or

constant expressions.

The correspondence between the types of file attributes referred to in this manual and

the types described in the File Attributes Reference Manual are described in “Using File

Attributes” later in this section.

Device Kind Assignment

5–40 8600 1047–506

Device Kind Assignment

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ<device mnemonic>ÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ KIND ÄÄ = ÄÙ ³

ÀÄ KIND ÄÄ = ÄÄ # ÄÄ<string primary>ÄÙ

Explanation

The KIND attribute specifies the type of device the file resides on.

The KIND = portion of the syntax is optional; it is enough to simply list the device

mnemonic.

Examples

The following two examples are equivalent:

FILE FILEA (TITLE = A/B, KIND = DISK);

FILE FILEA (TITLE = A/B, DISK);

The device mnemonic assigns a mnemonic value to the KIND attribute. For a list of the

valid mnemonic values, refer to the description of the KIND attribute in the File Attributes

Reference Manual.

Serial Number Assignment

8600 1047–506 5–41

Serial Number Assignment

ÄÄ SERIALNO ÄÄ = ÄÄ <serial number list> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄÂÄ<serial number>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ ( ÄÁÄ/9999\ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ) ÄÙ

ÀÄ<serial number>ÄÙ

ÄÄÂÄ <integer expression> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <string expression> ÄÄÙ

Explanation

Serial number assignments assign values to the SERIALNO file attribute. When the WFL

job or its tasks create or search for the file, they do so on the volumes with the specified

serial numbers. For further details, refer to the File Attributes Reference Manual.

The value assigned to the SERIALNO attribute is a string six characters long. If the serial

number given is an integer constant, it must be a positive integer less than or equal to

999999. The integer constant is automatically converted to a string with the correct

length. If the serial number given is a string constant less than six characters long, then it

is automatically padded with blanks at the end to ensure that the resulting string is the

correct length.

If a real constant or expression is specified for a serial number, it will be integerized with

truncation. This is equivalent to the WFL statement INTEGER (<real expression>).

When specifying a list of serial numbers for the reels of a multiple reel tape file, an empty

serial number can be specified for any of the reels.

Example

The following file equation assigns no serial number to the third reel of file T1:

FILE T1(KIND=TAPE, SERIALNO=(1,2,,4));

Using File Attributes

5–42 8600 1047–506

Using File Attributes

Table 5–3 shows how the attribute types listed in the File Attributes Reference Manual

correspond to the types used in this manual. Attribute types that cannot be accessed

through WFL are listed as not available.

Table 5–3. File Attribute Types

File Attribute

Type

Corresponding WFL Type

Valid File Attributes

Boolean <Boolean file attribute> All Boolean attributes

Event Not available None of the attributes

Integer <integer file attribute> All integer attributes

Mnemonic <mnemonic file attribute> All mnemonic attributes

Pointer <file name file attribute> The following attributes are

valid:

• FAMILYOWNER

• FILENAME

• PRINTCHARGE

• STATIONLIST

Pointer <long file name file attribute> LFILENAME attribute

Pointer <long title file attribute> LTITLE attribute

Pointer <name file attribute> The following attributes are

valid:

• APPLICATIONGROUP

• FAMILYNAME

• HOSTNAME

• INTNAME

• MYHOST

• MYHOSTGROUP

• SCRATCHPOOL

• YOURHOST

• YOURHOSTGROUP

• YOURUSERCODE

Using File Attributes

8600 1047–506 5–43

Table 5–3. File Attribute Types

File Attribute

Type

Corresponding WFL Type

Valid File Attributes

Pointer <string file attribute> The following attributes are

valid:

• AFTER

• DESTINATION

• FORMID

• LICENSEKEY

• NOTE

• PATHNAME

• RELEASEID

• TRANSFORM

• WARNINGS

Pointer <title file attribute> The following attributes are

valid:

• ALIGNFILE

• COPYNAME

• MYNAME

• SECURITYGUARD

• STATIONNAME

• TITLE

• YOURNAME

Real <real file attribute> All real attributes

Translatable Not available None of the attributes

Word <real file attribute> The following attributes are

valid:

• STATE

• TIMESTAMP

Word <serial number list> SERIALNO attribute

Using File Attributes

5–44 8600 1047–506

Assigning File Attributes

The attributes of files that are referenced in a WFL job can be assigned values in file

declarations and file assignment statements. One point to be aware of when using a file

assignment statement is that the attribute assignments can be executed in any order,

not necessarily in the order listed. Thus, file assignment statements such as the

following should be avoided:

F (TITLE=(SUPPLIES)COUNTEM,KIND=DISK,DEPENDENTSPECS=TRUE,OPEN=TRUE)

This example is intended to set certain attributes for a file, and then open it. However,

the OPEN assignment might be executed before the others, which would not give the

desired effect. The preferred method would be to use a separate OPEN statement

following the file assignment statement.

The OPEN attribute of a file is implicitly set by the OPEN statement, and reset by the

CRUNCH, LOCK, PURGE, RELEASE, and REWIND statements. These statements have

additional effects aside from setting or resetting this attribute; see the descriptions of

these statements in Section 6, “Statements.”

The OPEN statement can have the additional effect of assigning the logical file all

attributes of the physical file. This will occur if the physical file was pre-existing (not

created by the job) and the file is declared in the job with the DEPENDENTSPECS

attribute set to TRUE.

Example

The following file declaration associates the attributes of the physical file,

(JACOB)OBJECT/LINE, with the logical file, FILEA, when the file is opened:

FILE FILEA (TITLE=(JACOB)OBJECT/LINE,KIND=DISK,NEWFILE=FALSE,

DEPENDENTSPECS=TRUE);

This declaration provides the title and location of the file. The NEWFILE=FALSE

assignment indicates that a file with the specified title and location already exists and is

to be used rather than creating a new file of the same name.

When a file is declared in this way, the attributes that are not mentioned in the

declaration assume their default values until the file is opened. Thereafter, the attributes

will have the values of the physical file.

If a global file assignment is used to cause the task to use a file declared in the WFL job,

then any changes that the task makes to the file attributes are retained by the file

declared in the job. This is useful for making file attribute inquiries possible, but also can

cause side effects if the file is reused by another task.

These side effects can arise because tasks might have conflicting expectations about

whether a file is open or closed, and where the current record of the file is positioned.

WFL does not automatically close a file at the end of a task; however, the task can close

Using File Attributes

8600 1047–506 5–45

or rewind the file, and explicit file closing statements can be included in the WFL job to

accomplish the same result.

Interrogating File Attributes

WFL includes a number of expressions that can be used to interrogate the attributes of

files. Depending on the type of attribute involved, these expressions might return

integer, real, Boolean, or string values and can be used wherever that type of value is

permitted in the job.

Table 5–4 lists all these expressions. Refer to Section 7, “Expressions,” for the syntax of

each expression.

Table 5–4. Expressions for File Attribute Inquiry

File Attribute Type Expression Used

KIND <string file attribute primary>

SERIALNO The value of this attribute cannot be interrogated.

In general, a file must have been declared in the job before its attributes can be

interrogated. (The only exception is the file residence inquiry.) The syntax for file

declarations is given in Section 4, “Declarations.” The file should be declared with

DEPENDENTSPECS set to TRUE, as described under “Assigning File Attributes” earlier

in this section. Once the file is opened, the job can inquire about any of the attributes of

that file.

File attribute inquiries have a wide variety of applications in WFL jobs. For example, the

attributes of a file can be interrogated both before and after they are used by a task to

see if the task altered the attributes. However, the task must be made to use a file that

was declared in the job, because only the attributes of declared files can be interrogated.

Using File Attributes

5–46 8600 1047–506

A global file assignment can be used to make the task use a file. (Global file assignment

is described under “File Equations” earlier in this section.)

Another expression that is similar to a file attribute inquiry is the file residence inquiry,

which checks on the residence of a file. This same information can be obtained by using

a Boolean file attribute primary to interrogate the RESIDENT attribute of a file. However,

the file residence inquiry has the advantage that it can be applied to files regardless of

whether they were declared in the job. Refer to “File Residence Inquiry” in Section 7 for

more information on file residence inquiry.

Examples

The following example checks the length of a file by interrogating the value of the

LASTRECORD attribute. The file is copied to tape and removed from disk if it is larger

than 10000 records.

OPEN (FILEA);

I := FILEA (LASTRECORD) + 1; % LASTRECORD is 0-relative

IF I GTR 10000 THEN

BEGIN

WAIT ("MOUNT TAPE NAMED FILETP FOR BACKUP",OK);

COPY FILEA FROM ORDS (DISK) TO FILETP (TAPE) [T];

IF T(TASKVALUE) NEQ 1 THEN

REMOVE FILEA;

END;

The value of LASTRECORD is the zero-relative sequence number of the last line of the

file. Therefore, FILEA (LASTRECORD) + 1 returns the number of records in the file.

Before the disk file FILEA is removed, the TASKVALUE of the copy task is checked to

ensure that the copy was successful.

The security characteristics of a file can be inquired about through the SECURITYUSE,

SECURITYTYPE, and SECURITYGUARD attributes, each of which returns a string value.

For example:

IF FILEA (SECURITYUSE) NEQ "IO" THEN

SECURITY #FILEA(TITLE) IO;

This statement can be used to ensure that a file enables both input and output.

Nonresident Files

Statements can be initiated from different interactive sources such as MARC, CANDE, or

the ODT as well as from programming languages such as WFL. If one or more of the

necessary files are not present, the statement behavior can differ depending on how the

statement is initiated. For this reason, not all aspects of statement behavior are

documented.

Using File Attributes

8600 1047–506 5–47

To determine the commands that are acceptable when a NO FILE message is

encountered, use the Y (Status Interrogate) system command. For more information

about this command, refer to the System Commands Reference Manual.

Library Equation

5–48 8600 1047–506

Library Equation

ÄÄ LIBRARY ÄÄ <intname> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄ ( ÄÂÄÄÄÄÄÄÂÄÁÄ <library attribute assignment> ÄÁÄ ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ *, ÄÙ

ÄÄÂÄ <name constant> ÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ # ÄÄ <string primary> ÄÙ

ÄÄ <library attribute> ÄÄ = ÄÄ <library attribute value> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

Library equations can be used to change the attributes of libraries used by programs.

The intname in a library equation specifies the internal name used to identify a library.

The library attribute assignment assigns values to the attributes of libraries. For a list of

valid library attributes and library attribute values, refer to the Task Management Guide.

Examples

The following is an example of a library equation used after a COMPILE statement:

COMPILE OBJECT/PROG1 WITH ALGOL LIBRARY;

COMPILER FILE CARD = PROG1 ON DISK;

LIBRARY LIB1 (TITLE = OBJECT/LIB1, LIBACCESS = BYTITLE);

The following is an example of a library equation following a RUN statement:

RUN OBJECT/PROG2;

LIBRARY LIB2 (TITLE = OBJECT/LIB2, LIBACCESS = BYTITLE);

Overriding WFL Library Equations

It is possible for a task to override the WFL library equations that are assigned to it. WFL

library equations are merged only with those attributes specified in the library declaration

in the task. Library attribute assignments made later in the task override WFL library

equations.

Library Equation

8600 1047–506 5–49

Resolving Repeated Library Equations to the Same Library

When a given task equation list, compiler task equation list, task declaration, or task

assignment statement includes two or more library equations that apply to the same

internal library, the WFL compiler uses the following rules to decide which of the

specified library attribute assignments to use. These rules differ according to whether

the intname used is a name constant or a string primary.

If the intname used is a name constant, then the following rules apply:

• If a library equation includes an asterisk (*) before the library attribute assignments,

then its library attribute assignments are merged with any that have been specified

for the library in a previous library equation.

• If a library equation does not include the asterisk, all task attribute assignments

specified in previous library equations are discarded, and only the ones given in the

latest library equation are used.

If the intname used is a string primary, then the following rules apply:

• The library equation cannot contain an asterisk; if it does, a syntax error is given.

• If the string primary evaluates to the same internal library name as was specified in a

previous task equation, a run-time error is given.

Examples

In the following example, L1 is a name constant that specifies an intname. Because the

second library equation contains no asterisk, the first library equation is discarded, and

the value specified for the TITLE attribute is not used.

RUN (TEST)OBJECT/CALC;

LIBRARY L1(TITLE = TEST/L1);

LIBRARY L1(LIBPARAMETER = "TEST1");

In the following example, L1 is still a name constant that specifies an intname. However,

because the second library equation includes the asterisk, the attributes from both library

equations are merged.

RUN (TEST)OBJECT/CALC;

LIBRARY L1(TITLE = TEST/L1);

LIBRARY L1(*, LIBPARAMETER = "TEST1");

Database Equation

5–50 8600 1047–506

Database Equation

ÄÄ DATABASE ÄÄ<database name>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄ ( ÄÄ TITLE ÄÄ = ÄÄ<database title>ÄÄ ) ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ = ÄÄ<database title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄ <name constant> ÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ # ÄÄ <primary string> ÄÙ

ÄÄ <file title> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

A database equation causes a program to use a different database than it would

normally.

The database name is the name by which the database is referred to in the program.

Only the TITLE attribute of the database can be equated.

Example

The following is an example of a database equation following a RUN statement:

RUN OBJECT/UPDATE;

DATABASE TESTDB(TITLE=MYDB);

Local Data Specifications

8600 1047–506 5–51

Local Data Specifications

ÄÄÂÄ DATA ÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ EBCDIC ÄÙ ÀÄ <file name constant> ÄÙ

ëÄ <data images> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄ ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

A local data specification supplies input data in the form of card images to a particular

task. The task reads from the local data specification as if it were an input file. A task that

attempts to read from a card reader file will automatically read from a local data

specification instead, if one is available. Tasks that read from other kinds of files can be

file-equated to cause them to read from a local data specification instead.

Note: The default MAXRECSIZE of a READER file is 14 words (84 characters), but a

record contains only 80 characters of valid data. Take this into consideration when using

a local data specification, since a record in a file generated by CANDE with a FILEKIND =

JOBSYMBOL contains data in columns 1 through 80, spaces in columns 81 and 82, and

the sequence number in columns 83 through 90. To avoid getting unwanted information,

equate UNITS to CHARACTERS and set the MAXRECSIZE to 80 when reading the local

data specification.

The data images are records of EBCDIC data. DATA is a synonym for EBCDIC. The

construct that terminates the local data specification also separates the data specification

from the next statement; it is not necessary to follow the data specification with a

semicolon (;). For more information, see “Global Data Specifications” in Section 4.

A local data specification differs from a global data specification in that it can only be

used by a single task. The syntax for a local data specification is the same as that for a

global data specification, with the following exceptions:

• Local data specifications appear immediately after the task initiation statement for

the task that it is going to read from. Only task attributes and file equations can be

used between a task and its local data specifications.

• Local data specifications can be included in subroutines, while global data

specifications cannot.

• Local data specifications do not have to include a file name; the file name is optional.

When a task tries to open a card reader file, it searches among the local data

specifications associated with that task for the first unread local data specification with

the correct file name or no file name.

Local Data Specifications

5–52 8600 1047–506

Examples

The following example shows the simplest use of a local data specification. The program

(WALLY)OBJECT/COUNTUP expects to read data from a single card reader file. In this

situation, the local data specification does not need to be named, and no file equations

are required.

RUN (WALLY)OBJECT/COUNTUP;

DATA

? % End of data

It is a good idea to give each local data specification a title if more than one local data

specification is being used by the task. This makes it obvious which local data

specification is being substituted for which input file. The local data specification should

have the same title as the input file it is replacing in the program, unless the input file has

been file-equated to a different title.

In the following example, the program reads the local data specification titled TERMIN1

instead of the input file of the same name, and reads the local data specification titled

READDAT instead of the input file titled TERMIN2:

RUN (WALLY)OBJECT/COUNTTWO;

FILE TERMIN1(KIND=READER);

FILE TERMIN2(TITLE=READDAT,KIND=READER);

DATA TERMIN1

128

? % End of TERMIN1 data

DATA READDAT

? % End of READDAT data

When used after a COMPILE or BIND statement, local data specifications can be

interpreted as input to the compiler or to the program that is compiled depending on the

syntax used. Refer to “Compiler Task Equation List” in Section 6 for more information.

Local Data Specifications

8600 1047–506 5–53

By default, a compiler expects to find the program source in a card reader file named

CARD. For this reason, it is not necessary to include a file equation telling the compiler to

read from the appropriate local data specification. It is sufficient to assign CARD as the

title of the local data specification, and precede the local data specification with the word

COMPILER or a compiler name, as in the following example.

A data specification can appear only in jobs stored in disk files that are initiated by

START.

COMPILE OBJECT/X WITH ALGOL GO;

COMPILER PRINTLIMIT=1000;

PRINTLIMIT=2000;

COMPILER DATA CARD % Beginning of data for compiler

. % These lines contain an ALGOL program.

? % End of compiler data

DATA % Beginning of program data

? % End of program data

The form of the <name> construct that allows 17 EBCDIC characters other than

quotation marks (") is not supported.

Local Data Specifications

5–54 8600 1047–506

8600 1047–506 6–1

Section 6

Statements

Overview

The following section describes

• Functional groups of statements

• Statements in each group

• Each statement in alphabetical order

Many statements enable you to specify values for file attributes or task attributes.

However, the descriptions of file and task attributes covered in this section are discussed

only in terms of their use through WFL. If you require further information, refer to the File

Attributes Reference Manual for file attribute descriptions, and the Task Attributes

Reference Manual for task attribute descriptions.

Syntax Diagrams

The syntax diagrams for each statement often contain some elements that are explained

in Section 7, “Expressions,” and Section 8, “Basic Constructs.” Any statement can be

used wherever <statement> appears within a railroad syntax diagram.

Nested Statements

Statements in a job can be nested to a maximum depth of 19 levels. Examples of nested

statements include

• A statement specified in an ON statement

• An IF statement within an IF statement

• Statements within a compound statement

WFL Statement Groupings

6–2 8600 1047–506

WFL Statement Groupings

The following text describes each group of WFL statements and outlines the general

functions of each group and the statements within each group.

Null

Takes no action. This statement is sometimes useful in task control or nested

flow-of-control statements. The null statement is the only statement in this group.

Assignment

Assigns values to declared variables. The assignment statement is the only statement in

this group.

Compound

Groups other statements together so they can be included in the flow-of-control

statements. The compound statement is the only statement in this group.

Flow-of-Control

Controls the order in which statements are executed, or causes other statements to be

executed only if the specified conditions are met. Flow-of-control statements include:

• CASE

• DO

• GO

• IF

• WHILE

Subroutine Control

Invokes a subroutine, or causes it to be exited early. Subroutine control statements

include:

• <subroutine invocation statement>

• RETURN

Task Control

Affects task execution; for example, by discontinuing, delaying, or rerunning a task. Task

control statements include:

• ABORT

• INITIALIZE

• ON

• RUN

• STOP

• WAIT

WFL Statement Groupings

8600 1047–506 6–3

Task Initiation

Initiates a task, which is a process that runs in its own stack. Most task initiation

statements enable the use of file equations and task attribute assignments to control the

execution of the task. Refer to Section 5, “Task Initiation,” for details. Task initiation

statements include:

• ADD

• ARCHIVE DIFFERENTIAL

• ARCHIVE FULL

• ARCHIVE INCREMENTAL

• ARCHIVE MERGE

• ARCHIVE RESTORE

• ARCHIVE RESTOREADD

• ARCHIVE ROLLOUT

• BIND

• COMPILE

• COPY

• LOG

• PB

• PROCESS

• PTD

• RESTORE

• RUN

• START

Task Security

Affects the security privileges of the job. A related statement is the SECURITY

statement, which sets the security properties of files. Task security statements include:

• ACCESS

• PASSWORD

• USER

• VOLUME

Communication

Provides the user or the operator with information about the job. Communication

statements include:

• INSTRUCTION

• DISPLAY

File Handling

Opens or closes files. There are several ways of closing files, each of which leaves the

file in a different state. Refer to “File Handling” in Section 1 for more information. File

handling statements include:

• CHANGEPURGE

• CRUNCH

• LOCK

• OPEN

• RELEASED

• REWIND

WFL Statement Groupings

6–4 8600 1047–506

File Management

Changes, removes, or prints disk files. Creates permanent directories. Changes file titles

or security. The MODIFY statement permanently adds to or changes the attributes in an

object code file. File management statements include:

• ALTER

• ARCHIVE PURGE

• ARCHIVE RELEASE

• CHANGE

• MKDIR

• MODIFY

• PRINT

• REMOVE

• SECURITY

• VOLUME

Note: The ADD, COPY, MOVE, RESTORE, and RESTOREADD statements are related

to the file management statements, but are considered task initiation statements

because they initiate a task when copying files.

Cataloging

Affects the cataloging of information about files, disk families, or tapes. Cataloging

statements include:

• CATALOG

• VOLUME

ABORT Statement

8600 1047–506 6–5

ABORT Statement

ÄÄ ABORT ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄ´

ÀÄ [ ÄÄ <task identifier> ÄÄ ] ÄÙ ÀÄ <string expression> ÄÙ

Explanation

The ABORT statement

• Discontinues a task, or a job, and any tasks initiated by the job.

• Discontinues a task associated with the task identifier specified in the ABORT

statement.

• Discontinues a job and all the tasks initiated by a job if a task identifier is not

specified in the ABORT statement.

• Displays up to 430 characters of the value of the string expression prior to the abort,

if the string expression is specified in the ABORT statement.

Examples

The following are examples of the ABORT statement:

ABORT;

ABORT "THIS JOB HAS BEEN ABORTED";

IF T(TASKVALUE)=5 THEN ABORT;

In the following example, if the TASKVALUE attribute of task T2 has the value 3, the task

associated with the task identifier T1 is discontinued after the message “TASK

ABORTED” is displayed:

IF T2(TASKVALUE) = 3 THEN ABORT[T1] "TASK ABORTED";

In the following example, if the task state of the task T is not COMPILEDOK, the job is

discontinued, or in the case of an asynchronous subroutine, the subroutine is

discontinued:

IF T ISNT COMPILEDOK THEN ABORT[MYSELF];

ACCESS Statement

6–6 8600 1047–506

ACCESS Statement

ÄÄ access PASSWORD ÄÄ = ÄÄ <new accesscode password> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ <name constant> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The ACCESS statement

• Changes the ACCESSCODE password of the current job.

• Changes the password for the current ACCESSCODE to the new accesscode

password. However, at execution, the job must have a usercode and a valid

ACCESSCODE.

• Updates the password associated with the current ACCESSCODE of the job in the

USERDATAFILE when the job is successfully executed.

• Assigns an ACCESSCODE to a task, by using the accesscode assignment as

explained earlier in Section 5, “Task Initiation.”

Example

The following is an example of the ACCESS statement:

ACCESS PASSWORD = ENTER

ADD Statement

8600 1047–506 6–7

ADD Statement

ÄÄ ADD ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄÂÄ & ÄÄÄÂÄÂÄ /1\ ÄÄ BECOMEOWNER ÄÄÄÂÄÁÄÙ

ÀÄ AND ÄÙ ÃÄ /1\ ÄÂÄ CATALOG ÄÄÄÄÄÄ´

³ ÀÄ BACKUP ÄÄÄÄÄÄÄ´

ÃÄ /1\ ÄÂÄ COMPARE ÄÄÄÄÄÄ´

³ ÀÄ VERIFY ÄÄÄÄÄÄÄ´

ÃÄ /1\ ÄÂÄ DSONERROR ÄÄÄÄ´

³ ÀÄ WAITONERROR ÄÄ´

ÃÄ /1\ ÄÄ REPORT ÄÄÄÄÄÄÄÄ´

ÀÄ /1\ ÄÄ SKIPEXCLUSIVE ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ [ ÄÁÄÂÄ /1\ ÄÄ FROMSTART ÄÄÄÄÄÄÄÄÂÄÁÄ ] ÄÙ

ÀÄ /1\ ÄÄ<transfer service>ÄÙ

ÚêÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄ¿

ëÄÁÄ <copy request> ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ<task identifier>ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ ; ÄÄ<task attribute assignment>ÄÁÄÙ

Explanation

The ADD statement is similar to the COPY statement. It copies files between disks and

tapes. It is particularly useful for adding a directory of files to a disk where some of the

files are already resident and are to be preserved.

The ADD statement has the following effects which depend on whether a disk or tape

destination is specified:

• For a disk destination, the ADD statement copies only those files that are not already

resident on the specified disk destination.

• For a tape destination, it is equivalent to a COPY statement with a tape destination. If

there were any files on the destination tape, they will be overwritten. The ADD

statement will copy all the available requested files to the destination tape.

For a detailed explanation of the ADD statement syntax, refer to the “COPY or ADD

Statement” later in this section.

Example

The following example of the ADD statement copies files under the directory Z/= from

tape T to disk R and to DISK. Any files already resident on the destination volumes are

not copied. Different files might be copied to R and DISK, depending on what is already

resident on each destination volume before the ADD is executed.

ADD Z/= FROM T(KIND=TAPE) TO R(KIND=DISK), TO DISK;

ALTER Statement

6–8 8600 1047–506

ALTER Statement

ÄÄ ALTER ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ëÄÁÄÁÄÂÄ<long file title>ÄÄÄÄÄÄÂÄÁÄ ( ÄÄ<alter attribute statement>ÄÄ ) ÄÁÄ´

ÀÄ<long directory title>ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ ALTERNATEGROUPS ÄÄ = ÄÄ <alternategroups value> ÄÄÂÄÁÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ PROPAGATESECURITYTODIRS ÄÄÂÄ = ÄÂÄ DONTPROPATE ÄÂÄ´

ÃÄ PROPAGATESECURITYTOFILES ÄÙ ÀÄ PROPAGATE ÄÄÄÙ ³

ÃÄ ALIGNFILE ÄÄ = ÄÄ<file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ ALIGNMENT ÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ BANNER ÄÄÄÄÙ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ APL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ CCSVERSION ÄÄ = ÄÄ<mnemonic value>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ EXTMODE ÄÄ = ÄÄ<mnemonic value>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ FORMID ÄÄÄÄÂÄ = ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ PAGECOMP ÄÄ´ ³

ÃÄ TRANSFORM ÄÙ ³

ÃÄ<group expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ LABEL ÄÄÄÄÄÄÄÂÄ = ÄÄ<mnemonic>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ PRINTERKIND Ä´ ³

ÃÄ TRAINID ÄÄÄÄÄÙ ³

ÃÄ LOCKEDFILE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ NOTE ÄÄ = ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ PRODUCT ÄÄ = ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ RELEASEID ÄÄ = ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ SAVEFACTOR ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ SECURITYGUARD ÄÄ = ÄÂÄ<file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ "" ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ SECURITYMODE ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ SECURITYTYPE ÄÄ = ÄÄ<file mnemonic primary>ÄÄÄÄÄÄÄ´

ÃÄ SECURITYUSE ÄÄ = ÄÄ<file mnemonic primary>ÄÄÄÄÄÄÄÄ´

ÃÄ SENSITIVEDATA ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄ´

ÀÄ USERINFO ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄ "" ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ # ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ " ÄÁÄ/9\Ä<name constant>ÄÄ : ÄÂÄ RWX ÄÂÄÁÄ " ÄÙ

ÃÄ RW ÄÄ´

ÃÄ RX ÄÄ´

ÃÄ WX ÄÄ´

ÃÄ R ÄÄÄ´

ÃÄ W ÄÄÄ´

ÃÄ X ÄÄÄ´

ÀÄ NO ÄÄÙ

ALTER Statement

8600 1047–506 6–9

ÄÄÂÄ GROUP ÄÂÄ<name constant>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ # ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ "" ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ GROUPRWX ÄÂÄ = ÄÂÄ RWX ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ OTHERRWX Ä´ ÃÄ RW ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ OWNERRWX ÄÙ ÃÄ RX ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ WX ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ R ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ W ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ X ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ NO ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ # ÄÄ <string primary> ÄÄÄ´

ÃÄ GROUPR ÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ GROUPW ÄÄÄÄÄÄÄ´ ÀÄ = ÄÄ<Boolean expression>ÄÙ

ÃÄ GROUPX ÄÄÄÄÄÄÄ´

ÃÄ OTHERR ÄÄÄÄÄÄÄ´

ÃÄ OTHERW ÄÄÄÄÄÄÄ´

ÃÄ OTHERX ÄÄÄÄÄÄÄ´

ÃÄ OWNER ÄÄÄÄÄÄÄÄ´

ÃÄ OWNERR ÄÄÄÄÄÄÄ´

ÃÄ OWNERW ÄÄÄÄÄÄÄ´

ÃÄ OWNERX ÄÄÄÄÄÄÄ´

ÃÄ SETUSERCODE ÄÄ´

ÃÄ SETGROUPCODE Ä´

ÃÄ USEGUARDFILE Ä´

ÀÄ GUARDOWNER ÄÄÄÙ

Explanation

The ALTER statement changes the file attributes of a disk file.

When ALTER encounters a file that is currently open with EXCLUSIVE = TRUE, ALTER

enters a waiting state. To skip the file, enter <mixnumber> OF. To exit without

processing any more files, enter <mixnumber> DS.

The following file attributes are available for the <alter attribute statement>. Refer to the

File Attributes Programming Reference Manual for more information about each

attribute.

Notes:

• Many security attributes are interrelated, therefore changes to one attribute might

affect another attribute.

• The ENABLEPOSIX system option no longer controls functionality. However, you

still have the ability to control this option, which enables you to switch between the

current MCP and earlier MCP versions.

ALIGNFILE

Specifies the name of a printer backup file which contains an alignment pattern for a

particular form. This attribute is used by the Print System when the ALIGNMENT

attribute is TRUE.

ALTER Statement

6–10 8600 1047–506

ALIGNMENT

When set to TRUE, the Print System performs alignment before printing the file.

ALTERNATEGROUPS

Specifies a list of up to nine groups whose members can access the file in the manner

defined by the corresponding set of permissions. Any process executing a task with a

GROUPCODE or SUPPLEMENTARYGROUPS that matches the GROUP attribute of the

file or matches one of the groups specified in the ALTERNATEGROUPS attribute—but is

not the owner of the file—is granted the corresponding access permissions.

A process matching to multiple groups receives the union of the permissions granted for

the individual matches. If the ALTERNATEGROUPS attribute is not set, then it has no

effect on file access.

APL

When set to TRUE, specifies that only a program whose code file also has its APL

attribute set to TRUE can access the file. If the APL attribute is set to FALSE, the file can

be accessed by a program regardless of the APL attribute value in the program code file.

Note: This file attribute can be modified only if the ALTER statement is executed from

the ODT.

BANNER

When set to TRUE, a banner page is printed ahead of the desired file to help identify the

printed output.

CCSVERSION

Specifies the rules to be used for processing the character data in the file.

When you specify CCSVERSION, it is modified in the file and the EXTMODE attribute is

modified to a value compatible with the CCSVERSION specified.

If you specify both CCSVERSION and EXTMODE, and they are compatible with one

another, then both attributes are modified in the file. Incompatible values cause ALTER to

fail and an error message results.

For character-oriented files, if modifying the value of CCSVERSION or EXTMODE causes

the character size to change, ALTER fails and an error message results.

EXTMODE

Specifies the external or physical character encoding of the records in the file.

When you specify EXTMODE, it is modified in the file. The CCSVERSION attribute is

unaffected if it is compatible with the EXTMODE specified. Otherwise, CCSVERSION

reflects a value of NOTSET (-1) in the file.

If you specify both EXTMODE and CCSVERSION, and they are compatible with one

another, then both attributes are modified in the file. Incompatible values cause ALTER to

fail and an error message results.

ALTER Statement

8600 1047–506 6–11

For character-oriented files, if modifying the value of EXTMODE or CCSVERSION causes

the character size to change, ALTER fails and an error message results.

FORMID

When specified, the file can be printed only on a device with a matching identification.

This attribute is normally applied to indicate the kind of paper to be used.

GROUP

Specifies a group whose members can access the file in the manner defined by the

GROUPRWX attribute. Any process executing a task with a GROUPCODE or

SUPPLEMENTARYGROUPS that matches the GROUP attribute of the file—but is not the

owner of the file—is granted the access permissions defined by the GROUPRWX

attribute. If the GROUP attribute is not set, then group access is not granted to any

process attempting to access the file.

GROUPR

When set to TRUE, grants group members read-access to the file.

GROUPW

When set to TRUE, grants group members write-access to the file.

GROUPX

When set to TRUE, grants group members execute-access to the file.

GROUPRWX

Specifies the manner in which members of the group matching the group attribute of the

file are permitted to access the physical file. The following table lists the valid mnemonic

values for GROUPRWX:

Mnemonic Meaning

RWX Read, Write, Execute

RW Read, Write

RX Read, Execute

R Read

WX Write, Execute

W Write

X Execute

NO None

Family substitution is used if the job or task has an active family specification. Only the primary

family name is used. Refer to “FAMILY Assignment” and “Interrogating Complex Task

Attributes” in Section 5.

ALTER Statement

6–12 8600 1047–506

GUARDOWNER

Used with the USEGUARDFILE attribute to cause the guard file to define access

permissions for the owner of the file.

Note: The GUARDOWNER attribute has no effect if the USEGUARDFILE attribute is

reset.

LABEL

For tape files, controls whether labels are written and affects end-of-file action.

For disk and printer files, controls whether banner pages are printed and affects top-of-

page action.

LOCKEDFILE

When set to TRUE, prevents disk files from being removed or replaced, and the file

name from being changed. However, the locked file can be opened and updated, and the

file attributes can be changed. When set to FALSE, this attribute enables files to be

removed and changed.

NOTE

Stores a message of up to 250 characters to be printed on the banner page preceding

the printer file, punch file, or disk file. The default value is a null string.

OTHERR

When set to TRUE, grants other users (excluding the owner and members of the groups

specified by GROUP and ALTERNATEGROUPS) read-access to the file.

OTHERW

When this file attribute is set to TRUE, then other users (excluding the owner and

members of the groups specified by GROUP and ALTERNATEGROUPS) are granted

write-access to the file.

OTHERX

When set to TRUE, grants other users (excluding the owner and members of the groups

specified by GROUP and ALTERNATEGROUPS) execute-access to the file.

OTHERRWX

Specifies the manner in which all other users (excluding the owner and members of the

groups specified by GROUP and ALTERNATEGROUPS) are permitted to access the

physical file. The following table lists the valid mnemonic values for OTHERRWX:

Mnemonic Meaning

RWX Read, Write, Execute

RW Read, Write

RX Read, Execute

ALTER Statement

8600 1047–506 6–13

Mnemonic Meaning

R Read

WX Write, Execute

W Write

X Execute

NO None

Family substitution is used if the job or task has an active family specification. Only the primary

family name is used. Refer to “FAMILY Assignment” and “Interrogating Complex Task

Attributes” in Section 5.

OWNER

Modifies the owner of the file.

Note: This attribute can be set only within a permanent directory namespace.

OWNERR

When set to TRUE, grants the owner read-access to the file.

OWNERW

When set to TRUE, grants the owner write-access to the file.

OWNERX

When set to TRUE, grants the owner execute-access to the file.

OWNERRWX

Specifies the manner in which the owner of the file is permitted to access the physical

file. The following table lists the valid mnemonic values for OWNERRWX:

Mnemonic Meaning

RWX Read, Write, Execute

RW Read, Write

RX Read, Execute

R Read

WX Write, Execute

W Write

X Execute

NO None

ALTER Statement

6–14 8600 1047–506

Family substitution is used if the job or task has an active family specification. Only the primary

family name is used. Refer to “FAMILY Assignment” and “Interrogating Complex Task

Attributes” in Section 5.

PAGECOMP

Specifies formatting options to be used when printing a file.

PRINTERKIND

Specifies the kind of device the file is to be printed on.

PRODUCT

Stores a message of up to 250 characters to specify or determine that a piece of your

software belongs to a product group. This attribute associates a piece of software with a

specific application, product, and component as defined within the Unisys tracking and

reporting system.

PROPAGATESECURITYTODIRS

When set to PROPAGATE on a permanent directory, causes subdirectories within the

permanent directory—for which no security attributes have been explicitly set—to be

assigned the same security attributes as the parent directory.

Note: Permanent directories are supported only on ClearPath HMP NX Series systems.

PROPAGATESECURITYTOFILES

When set to PROPAGATE on a permanent directory, causes files within the permanent

directory—for which no security attributes have been explicitly set—to be assigned the

same security attributes as the parent directory.

Note: Permanent directories are supported only on ClearPath HMP NX Series systems.

RELEASEID

Specifies or determines the release level of the file.

SAVEFACTOR

Indicates the expiration date of a file in terms of the number of days past the creation

date.

SECURITYGUARD

Identifies the guard file to be invoked for the file if the SECURITYTYPE attribute is

assigned GUARDED or CONTROLLED. For more information about guard files, refer to

the Security Features Guide.

SECURITYMODE

Specifies the manner in which users are permitted to access the physical file, including

the owner of the file.

ALTER Statement

8600 1047–506 6–15

SECURITYTYPE

Provides access control over users, other than the owner of a file, to a physical file. The

SECURITYTYPE attribute can have a value of PRIVATE (default), PUBLIC, GUARDED, or

CONTROLLED:

• PRIVATE files can be accessed or overwritten only by their owners and privileged

users.

• PUBLIC files can be accessed by tasks with any usercode, as limited by the setting

of the SECURITYUSE attribute.

• GUARDED files can be accessed by the owner, however, nonprivileged users and

programs are granted access as defined by the guard file. The guard file, which

defines the access rights to files, must be examined before access to a disk file is

granted.

• CONTROLLED files can be accessed after the guard file is examined and access to

your disk file is granted. If you are not defined in the guard file, you do not have

access to the file.

SECURITYUSE

Specifies how a physical file that is protected by security can be accessed by

nonprivileged users using nonprivileged programs. This attribute can have a value of IO

(default), IN, or OUT. When a PUBLIC file is accessed by a task with a usercode that

differs from the OWNER, the SECURITYUSE attribute permits the following actions

based on its value:

• A value of IO permits reading, writing, overwriting, and purging.

• A value of IN permits reading, but not writing, overwriting, or purging.

• A value of OUT permits writing, overwriting, or purging, but not reading.

SENSITIVEDATA

When set to TRUE, causes the disk or pack areas assigned for a file to be overwritten

with an arbitrary pattern before the disk space is returned to the system for reallocation.

SETGROUPCODE

When set to TRUE on a code file, this file attribute causes the program to execute with

an effective GROUPCODE of the group of the file.

SETUSERCODE

When set to TRUE on a code file, causes the program to execute with an effective

USERCODE of the owner of the file.

TRAINID

Specifies the print train to be used on a train printer.

TRANSFORM

Specifies a transform function, which is used to manipulate the data before printing.

ALTER Statement

6–16 8600 1047–506

USEGUARDFILE

When set to TRUE, a guard file in addition to the SECURITYMODE attribute controls

access to the physical file. For the guard file to control access to the file completely, the

file access permission flags OWNERRWX, GROUPRWX, and OTHERRWX should be set

to TRUE.

USERINFO

Saves site- or application-specific information.

Examples

This ALTER statement prevents a file named FILEX from being removed or replaced, and

the file name from being changed.

ALTER FILEX (LOCKEDFILE)

This statement locks the files called MYFILE and AFILE so that the files cannot be

replaced or removed, and sets their SECURITYUSE attribute to permit reading only.

ALTER MYFILE, *SOURCE/AFILE (LOCKEDFILE=TRUE, SECURITYUSE=IN)

The first line of this statement locks the file called FILEY and all files in the directory

called MYFILE, and changes the SENSITIVEDATA attribute for those files. The second

line of this statement sets the expiration date of FILEX to 30 days past its creation, sets

the NOTE attribute of FILEX to “Banner Page”, and locks the file.

ALTER FILEY, MYFILE/= (SENSITIVEDATA, LOCKEDFILE),

FILEX (SAVEFACTOR=30, NOTE="Banner Page", LOCKEDFILE)

Archive Subsystem

8600 1047–506 6–17

Archive Subsystem

Note: Archiving is not supported for files within the permanent directory namespace.

The archive subsystem consists of six different ARCHIVE statements. These statements

enable you to

• Copy files to archive backup tape and CD-ROM volumes.

• Maintain a record of the names, locations, and attributes of the archived files and

directories.

• Remove archive backup information for specified files.

• Transfer archived files between backup tapes.

• Restore archived files to disk.

• Merge files onto a single tape or tape set.

The following paragraphs briefly describe the functions of the ARCHIVE statements:

• Copying, transferring, and restoring files

You can perform library maintenance operations that include copying and transferring

disk files to backup tape and CD-ROM volumes, restoring disk files from backup tape

and CD-ROM volumes, and merging backup tape and CD-ROM volumes to a single

tape or tape set.

• Automatically maintaining an archive directory

The archive directory is a disk directory that records the names, locations, and

attributes of disk files that have been transferred through archive operations to tape

or CD-ROM volumes, or merged from many tape and CD-ROM volumes to one tape

or tape set. The archive subsystem maintains an archive directory for each online

disk family from which archive operations have been performed. These directories

reside on the DL CATALOG family.

• Controlling access using the support library

The support library is used by the ARCHIVE statement to control which files are

copied during an archive operation. The archive support library rejects files that are

requested by ARCHIVE statements based on various selection criteria. The support

library is sometimes called the selector library.

Archive Subsystem

6–18 8600 1047–506

Specifying Different ARCHIVE Statements

The following table lists all of the ARCHIVE statements and their functions.

At many sites, the use of the ARCHIVE statements to manipulate files under usercodes

other than your own is limited to those usercodes whose security access is privileged.

However, a WFL job that is started at an ODT without a usercode can use any one of the

following ARCHIVE RESTORE statements.

ARCHIVE DIFFERENTIAL

ARCHIVE FULL

ARCHIVE INCREMENTAL

Copy resident disk files to library maintenance tape or CD-ROM volumes and are referred

to as ARCHIVE backup statements.

ARCHIVE MERGE

Merges files from two or more library maintenance tape or CD-ROM volumes to a single

tape or tape set.

ARCHIVE PURGE

Removes the backup records for specific files or directories from the archive directory of

the specified disk family. This statement does not affect resident disk files in any way.

ARCHIVE RELEASE

Removes files from disk that are not in use and have up-to-date archive backup records.

This statement is intended to free disk space for other uses. The removed files can be

restored by the archive AUTORESTORE feature and the WFL statements ARCHIVE

RESTORE and ARCHIVE RESTOREADD. In addition to the ARCHIVE RELEASE

statement, see the WFL statements REMOVE and REMOVE DESTROY.

ARCHIVE RESTORE

ARCHIVE RESTOREADD

Restore archived files from library maintenance tape and CD-ROM volumes to disk.

ARCHIVE ROLLOUT

Selects and copies disk files to a library maintenance tape and CD-ROM volumes. It then

removes the original disk files from the disk. This statement is intended to free disk

space for other uses.

FAMILY Specifications

Family substitution is used if the job or task has an active family specification. Only the

primary family name is used. Refer to “FAMILY Assignment” and “Interrogating

Complex Task Attributes” in Section 5.

Archive Subsystem

8600 1047–506 6–19

ARCHIVE Backup Statement

ÄÄ ARCHIVE ÄÂÄ FULL ÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÃÄ INCREMENTAL ÄÄ´ ÀÄ <archive options> ÄÙ

ÀÄ DIFFERENTIAL ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄë

ÃÄ FROM ÄÄ <archive disk volume> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

³ ³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³ ³

ÀÄÁÄÁÄÂÄ <long file name> ÄÄÄÄÄÄÂÄÁÄ FROM ÄÄ <archive disk volume> ÄÁÄÙ

ÀÄ <long directory name> ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÃÄ TO ÄÄ<archive CD-R volume>ÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ TO ÄÄ <archive tape volume> ÄÁÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ <task identifier> ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ; ÄÄ <archive task equation list> ÄÙ

Explanation

These ARCHIVE statement copies resident disk files to backup tape or CD-ROM

volumes. You can use these statements to backup some or all of the disk files on various

families; which files the archive subsystem selects for backup depends on which of the

three statements you select.

The three variants of the ARCHIVE backup statement are as follows:

• ARCHIVE FULL

Copies all specified resident disk files on the named families to a CD-ROM volume or

to one or more backup tapes.

• ARCHIVE INCREMENTAL

Copies to backup CD-ROM or tape volumes only those specified resident disk files

that have been changed or added since the last archive backup procedure was

performed. This statement does not copy files solely on the basis of the last full

archive operation.

• ARCHIVE DIFFERENTIAL

Copies to backup CD-ROM or tape volumes the specified resident disk files that have

been changed or added to the family or families since the last ARCHIVE FULL

statement was executed.

For each of the ARCHIVE backup statements, files are selected by the disk subsystem

and then accepted or rejected for the actual archive procedure. The archive support

library determines which of the candidate files can and cannot be archived to a tape or

CD-ROM volume.

If your installation has compiled its own selector support library, you can use library

equation to direct the file selection process through that library.

Archive Subsystem

6–20 8600 1047–506

You can use the backup CD-ROM and tape files created by these statements as input for

the ARCHIVE MERGE, ARCHIVE RESTORE, and ARCHIVE RESTOREADD statements,

and for the COPY and ADD statements.

Special Considerations for Backup Tape and CD-ROM Volumes

It is necessary to plan what volume names and, optionally, what serial numbers to use

for the backup volume. Otherwise, archive restore requests result in the following RSVP

messages for the CD-ROM volumes it decides to use:

NO FILE <volume name>/FILE000 (MT) [<serial number>]

NO FAMILY <volume name> (CD) [<serial number>]

The operator must have a method to find those tape CD-ROM volumes and load them

onto a CD-ROM unit. Keep in mind the following considerations:

• Tape volumes always have serial numbers that you assign in advance with the SN

(Serial Number) system command. The serial numbers for tape volumes are usually

unique, so it is relatively easy to build a tape library with each volume stored

according to its serial number.

• For CD-ROM volumes, you cannot assign the serial numbers in advance, and when

you do specify a serial number in an archive backup request, the archive system puts

the same serial numbers on all the CD-ROM volumes created by that backup

request.

Therefore, you should systematically assign volume names and, optionally, serial

numbers to CD-ROM volumes for each archive backup request you issue and store those

CD-ROM volumes in an organized library so that operators can locate them when archive

restore asks for them.

Checking the Progress of the Backup

You can use the HI (Cause Exception Event) system command to check the progress of

an ARCHIVE backup statement. A command of the form <mix number> HI displays the

number of files already copied and other information.

Special Code for Streamer Tapes

When you copy files from disk to certain tapes, the archive backup process uses special

code to accelerate the copy process to streamer tapes—if all of the following conditions

are met:

• There is only one destination tape.

• The destination tape unit is one of the following:

IOM Systems

− 2145–01 and 2145–03 tape units

EMS Systems

− 2145–02 and 2145–03 tape units

− B9498 Cipher Streamer tape units

Archive Subsystem

8600 1047–506 6–21

• You do not specify any of the following options:

− & DSONERROR

− & WAITONERROR

− & VERIFY

− & REPORT

Note: You can specify the & COMPARE option.

Examples

The following example illustrates how to perform a complete backup of the TESTPACK

family:

ARCHIVE FULL FROM TESTPACK

The following example shows how to perform a complete backup of all online families:

ARCHIVE FULL

The following example creates backup copies of the files under the SYSTEM directory on

the families DISK and HLUNIT that do not already have archive backup copies:

ARCHIVE INCREMENTAL & VERIFY SYSTEM/= FROM DISK,

SYSTEM/= FROM HLUNIT TO SYSTAPE;

The following example illustrates how to perform a backup of files under the usercode

DOE on the family TESTFAMILY that have been updated since the last ARCHIVE FULL

statement:

ARCHIVE DIFFERENTIAL (DOE) = FROM TESTFAMILY

The following example shows how to back up files under the usercode MYCODE to a

tape volume called NEWTAPE from the scratch pool POOL1:

ARCHIVE DIFFERENTIAL (MYCODE) = FROM TESTFAMILY

TO NEWTAPE (KIND = TAPE, SCRATCHPOOL = POOL1);

The following example shows how to perform a complete backup of the XDATA disk

family to CD-ROM volumes. In this case, because CDCOPIES is 2, the system produces

duplicate copies of the files onto two sets of CD-ROM volumes.

ARCHIVE FULL *= FROM XDATA

TO XDARC (KIND=CD, CDCOPIES=2, SERIALNO=555555);

In this example, both sets of CD-ROM volumes get the name XDARC and the serial

number 555555. If more files are on the disk family XDATA than fit on one CD-ROM

volume, then the system requests additional CD-ROM volumes during the copy process.

The system gives those additional CD-ROM volumes the volume name XDARC and the

serial number 555555 also.

Archive Subsystem

6–22 8600 1047–506

ARCHIVE Statement Options

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÙ

ÃÄ/1\ÄÂÄ & ÄÄ COMPARE ÄÄÄÄÄ´

³ ÀÄ & ÄÄ VERIFY ÄÄÄÄÄÄ´

ÃÄ/1\ÄÂÄ & ÄÄ DSONERROR ÄÄÄ´

³ ÀÄ & ÄÄ WAITONERROR Ä´

ÃÄ/1\Ä & ÄÄ RELEASE ÄÄÄÄÄÄÄ´

ÃÄ/1\Ä & ÄÄ REPORT ÄÄÄÄÄÄÄÄ´

ÀÄ/1\Ä SKIPEXCLUSIVE ÄÄÄÄÄÄÙ

Explanation

The following table options are available for all of the ARCHIVE statements.

COMPARE

Compares the input file and the output file bit by bit immediately after the file is copied. If

a compare error occurs, the process will stop and ask the operator if the file should be

recopied.

DSONERROR

Causes the system to discontinue the archiving process if any error is detected.

RELEASE

Causes library maintenance to execute an “archive release” operation for each file that

library maintenance successfully copies and archives. The archive release operation

removes the resident version of the file from the disk. You can use the RELEASE option

only in ARCHIVE FULL, ARCHIVE INCREMENTAL, and ARCHIVE DIFFERENTIAL

statements.

Note: Library maintenance does not release a file that is in use by another program.

REPORT

Causes library maintenance to print a report of the files it copied and any errors

encountered. When & REPORT is specified, library maintenance does not write “file

copied” messages in the job log or the system sumlog.

SKIPEXCLUSIVE

Causes the system to not copy those files from disk that are opened with

EXCLUSIVE=TRUE or that are KEYEDIOII files marked as being updated.

WAITONERROR

Causes the archive process to issue an RSVP message whenever an error occurs during

the archive process.

Archive Subsystem

8600 1047–506 6–23

Examples of possible errors include: requesting a file or directory that is missing, or

failing to open a tape successfully. The RSVP message halts the archive process until the

operator or programmer responds with OK or DS. A response of OK causes the archive

process to continue archiving with other files or tapes. A response of DS will terminate

the archive process. After investigating the error which created the RSVP message, you

can re-issue the archive statement.

VERIFY

This option is similar to the COMPARE option. However, instead of comparing the copied

file bit by bit, the file is read again and its overall checksum is compared. When copying

to a CD-ROM volume, the system ignores the VERIFY option.

ARCHIVE Disk Volume

ÄÄ <family name> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <archive disk volume attribute list> ÄÙ

Explanation

The archive disk volume syntax designates the disk that contains the files where an

archive function is going to be performed.

The archive functions that you can perform on the source disk include:

• Archiving files

• Restoring files

• Releasing files

• Purging archive information for files from a specific archive directory

Archive Subsystem

6–24 8600 1047–506

ARCHIVE Disk Volume Attribute List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ( ÄÁÄÂÄ /1\ ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄ DISK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ) ÄÄÄÄ´

³ ÀÄ KIND ÄÄ = ÄÙ ÀÄ PACK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ /1\ ÄÄ SERIALNO ÄÄ = ÄÄ <serial number list> ÄÄÄÄ´

ÀÄ /1\ ÄÄ FAMILYINDEX ÄÄ = ÄÄ <integer expression> ÄÙ

Explanation

The following options are available for the archive disk volume attribute list.

KIND

Describes the peripheral unit associated with the volume.

SERIALNO

Identifies the specific disk family to be used when copying files. This attribute does not

have a default value. For more information, refer to “Serial Number Assignment” in

Section 5.

FAMILYINDEX

Designates a specific physical volume within a disk family. If you do not specify the

FAMILYINDEX attribute, the FAMILYINDEX attribute (if any) of each file to be restored is

used.

Note: This option applies only to the ARCHIVE RESTORE and RESTOREADD

statements.

Archive Subsystem

8600 1047–506 6–25

ARCHIVE Tape Volume

ÄÄ <tape name> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <archive tape volume attribute list> ÄÙ

Explanation

The tape name specifies the name of the destination tape for the archived files. If you do

not specify a tape name, the system will create a name. For instance, if there is more

than one <file list> FROM <family name> clause in an ARCHIVE FULL, ARCHIVE

INCREMENTAL, or ARCHIVE DIFFERENTIAL statement, the system uses the tape name

FULL, INCREMENTAL, or DIFFERENTIAL followed by the date in the form YYDDD,

where YY is the year and DDD is the day of the year. Otherwise, the system uses a tape

name that consists of the disk family name followed by the date in the form YYDDD.

Examples

The following example causes the system to generate a tape name of the form

INCREMENTAL95302:

ARCHIVE INCREMENTAL = FROM DISK, = FROM HLUNIT;

The following example causes the system to generate a tape name of the form

DISK95302:

ARCHIVE FULL & COMPARE = FROM DISK;

Archive Subsystem

6–26 8600 1047–506

ARCHIVE Tape Volume Attribute List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ( ÄÁÄÂÄ/1\Ä AUTOUNLOAD ÄÄ = ÄÂÄ ON ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ) ÄÄÄÄÄ´

³ ÃÄ OFF ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ DONTCARE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä BLOCKSIZE ÄÄ = ÄÄ<integer>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä COMPRESSIONCONTROL ÄÄ = ÄÂÄ USER ÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ SYSTEM ÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä COMPRESSIONREQUESTED ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄ´

ÃÄ/1\Ä DENSITY ÄÄ = ÄÂÄ BPI800 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI1250 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI1600 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI6250 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI11000 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI38000 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMT36TRK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTAIT ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTAIT2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDLT10 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDLT20 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDLT35 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTQIC1000 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ FMTST9840 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä FAMILYOWNER ÄÄ = ÄÂÄ "" ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<usercode>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ TAPE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ KIND ÄÄ = ÄÙ ³

ÃÄ/1\ÄÂÄ LIBMAINTAPPEND ÄÂÄ NO ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÀÄ TOEND ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ LIBMAINTDIR ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä LOCATECAPABLE ÄÂÄ ON ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ OFF ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ DONTCARE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä OFFSITE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SAVEFACTOR ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄ´

ÃÄ/1\Ä SECURITYGUARD ÄÄ = ÄÄ<guard file title>ÄÄÄÄÄ´

ÃÄ/1\Ä SECURITYTYPE ÄÄ = ÄÄ<file mnemonic primary>Ä´

ÃÄ/1\Ä SECURITYUSE ÄÄ = ÄÄ<file mnemonic primary>ÄÄ´

ÃÄ/1\ÄÂÄ SERIALNO ÄÄ = ÄÄ<serial number list>ÄÄÄÄÄÄ´

³ ÀÄ SCRATCHPOOL ÄÄ = ÄÄ<scratch pool name>ÄÄÄÄ´

ÀÄ/1\Ä USECATALOG ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄ <name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Archive Subsystem

8600 1047–506 6–27

Attributes

You can specify the following attributes for the archive tape volume attribute list:

• AUTOUNLOAD

• BLOCKSIZE

• COMPRESSIONCONTROL

• COMPRESSIONREQUESTED

• DENSITY

• FAMILYOWNER

• KIND

• LIBMAINTAPPEND

• LIBMAINTDIR

• LOCATECAPABLE

• OFFSITE

• SAVEFACTOR

• SCRATCHPOOL

• SECURITYGUARD

• SECURITYTYPE

• SECURITYUSE

• SERIALNO

• USECATALOG

AUTOUNLOAD

Determines whether or not a tape is unloaded when it is released by the system during a

reel switch or a file close operation. If the value is ON, the tape is rewound and unloaded.

If the value is OFF, the tape is not unloaded. If the value is DONTCARE, or if this attribute

is not specified, the tape behavior is controlled by the setting of the AUTOUNLOAD

option of the MODE (Unit Mode) system command. For more information, refer to the

System Commands Reference Manual.

BLOCKSIZE

Specifies the tape blocksize in words that library maintenance uses when copying files to

and from tape. Library maintenance automatically rounds the value you specify up to an

integer multiple of 900 words. If you specify a value larger than 64800 words, library

maintenance uses 64800 instead. If you specify a value greater than 4500 words for a

tape destination, then library maintenance automatically uses that blocksize for all disks

involved in the operation.

Using the same block size for the source and all the destinations greatly improves the

performance of the copy task. Using a larger blocksize increases the amount of data that

can be stored on any given tape volume.

Notes:

• Certain magnetic tape devices have limits on the maximum length I/O they can

process. If you specify a block size larger than the limit for a tape device, library

maintenance automatically reduces the blocksize to a valid value for that tape

destination.

Archive Subsystem

6–28 8600 1047–506

• ARCHIVE WFL statements that contain BLOCKSIZE specifications cannot be

compiled or run on SSR 42.2 or earlier versions of the MCP. The SSR 42.2 and earlier

versions of the MCP will give syntax errors for ARCHIVE statements containing

BLOCKSIZE specifications. The SSR 42.2 and earlier versions of the MCP will give

“file OPEN errors” for any ARCHIVE statement with a BLOCKSIZE specification for a

tape that is started or restarted on an SSR 42.2 or earlier versions of the MCP.

• If you do not specify BLOCKSIZE for a tape, library maintenance uses the default

value established by the SYSOPS LMBLOCKSIZE system command; or if the default

is zero (0), library maintenance uses a small default blocksize that it selects for each

tape and disk.

COMPRESSIONCONTROL

Enables you to control whether compression will be applied to the volume being created.

There are two values associated with this attribute:

• USER

• SYSTEM

When the value of USER is selected, compression will occur based on the value of the

COMPRESSIONREQUESTED file attribute. When the value SYSTEM is selected,

compression will occur based on the compression value in the tape label. SYSTEM is the

default value. For further information, refer to the File Attributes Reference Manual.

COMPRESSIONREQUESTED

This attribute only has significance for tape files when the COMPRESSIONCONTROL

attribute is set to a value of USER.

• If COMPRESSIONCONTROL = USER and COMPRESSIONREQUESTED = TRUE,

compression will occur.

• If COMPRESSIONCONTROL = USER and COMPRESSIONREQUESTED = FALSE,

compression will not occur.

Note: Stating COMPRESSIONREQUESTED in a WFL statement implies

COMPRESSIONREQUESTED = TRUE. For further information, refer to the File Attributes

Reference Manual.

DENSITY

Indicates the recording density of a magnetic tape volume. The default value is the

density setting of the tape unit selected.

Archive Subsystem

8600 1047–506 6–29

FAMILYOWNER

Indicates the usercode of the owner of a tape volume family. If you do not use the

FAMILYOWNER attribute or if you specify a null string (" "), the usercode of the archive

process is used. If you specify an asterisk (*) with the FAMILYOWNER attribute, the

tape volume becomes a nonusercoded volume.

Note: This attribute applies only to installations running the Security Accountability

Facility package or the InfoGuard security enhancement software.

KIND

Specifies the kind of peripheral unit to use. KIND can be TAPE or CD (or CDROM).

LIBMAINTAPPEND

This attribute is used by library maintenance in the copy procedure.

Notes:

• Library maintenance does not update the tape directories on any reels already copied

with the file names of the files being added. Library maintenance only updates the

LIBMAINTDIR tape directory disk files with the names of the new files.

• The message BACKUP START ON: data and time appears in the PD display for files

that have archive backups. This message refers to the time of the original task that

started the tape. It does not refer to the start time of the task with

LIBMAINTAPPEND = TOEND specified.

LIBMAINTAPPEND = NO

If you specify LIBMAINTAPPEND = NO, or do not specify LIBMAINTAPPEND, the copy

procedure copies to a new tape.

LIBMAINTAPPEND = TOEND

If you specify LIBMAINTAPPEND = TOEND, library maintenance searches for an existing

library maintenance tape with the name and serial number you specify. The tape you

specify must be a tape created with the LIBMAINTDIR = TRUE specification. Library

maintenance checks the LIBMAINTDIR tape directory disk file for that tape to determine

the serial number of the last tape in that set of tapes. (Even if the tape contains no tape

directory, it does contain a pointer to the LIBMAINTDIR file on disk, which is used to find

the location of the end of the last file on the final tape.)

If necessary, library maintenance searches for that tape. Then library maintenance skips

to the end of the last file copied to that tape and copies the files that you specified. The

copy procedure expands the LIBMAINTDIR tape directory disk file for the tape with the

names and status of all files copied to the LIBMAINTDIR file.

Archive Subsystem

6–30 8600 1047–506

The following conditions must be met to use LIBMAINTAPPEND = TOEND:

• The destination tape must have been created by a COPY or ARCHIVE statement that

specifies LIBMAINTDIR = TRUE for that tape.

• You must specify & VERIFY for the append operation if the & VERIFY option was

specified when the tape was originally created.

• You must not specify & VERIFY for the append operation if the & VERIFY option was

not specified when the tape was originally created.

When library maintenance copies files to a tape with LIBMAINTAPPEND = TOEND, it

does not add the names of those files to the tape directory for the tape. You cannot use

the TDIR system command or the FILEDATA utility TAPEDIR request to view the names

of files copied to tape with LIBMAINTAPPEND = TOEND. Instead, use the FILEDATA

utility LIBMAINTDIR modifier to view the names of all the files copied to a tape.

If you specify a list of tape serial numbers for the SERIALNO attribute, library

maintenance takes special action. Library maintenance uses the first serial number in

the list to locate any existing tapes in the set of tapes to which the files are to be added

or appended. Library maintenance then reads the LIBMAINTDIR file for that tape to

determine the serial number of the last tape volume in the set. Library maintenance

immediately opens that tape, if necessary, then uses the other serial numbers you

supplied when it reaches the end of that tape.

Example

The original tapes have the serial number 111111, 222222, and 333333, and the following

COPY statement is specified:

COPY . . . TO <tape name> (LIBMAINTAPPEND = TOEND,

SERIALNO = (222222, "AAAAAA"));

The preceding COPY statement is processed as follows:

1. The tape with serial number 222222 opens and the LIBMAINTDIR file is read. It is

determined that the tape 333333 is the last tape in the set.

2. Tape 222222 closes.

3. Tape 333333 opens.

4. Library maintenance moves to the end of the last file on tape 333333.

5. Library maintenance appends three new files to the end of tape 333333.

6. If tape 333333 fills before the copy operation completes, tape AAAAAA opens and

the additional data is appended to tape AAAAAA.

LIBMAINTDIR

Determines whether library maintenance should create a tape directory disk file on the

DL LIBMAINTDIR disk family. The LIBMAINTDIR tape directory disk file describes the

destination tape and the files copied to it. Library maintenance gives these files names of

the form LIBMAINTDIR/<tape name>/<date>/<tape serialno>. It also puts them under

the usercode that library maintenance is running under, or * if there is no usercode.

Archive Subsystem

8600 1047–506 6–31

Library maintenance stores the following information in these files:

• Serial numbers of the tapes used

• Names of the files copied to those tapes

• Certain other attributes of those files

You receive a report of the information in tape directory disk files by running the

SYSTEM/FILEDATA utility program and using the following syntax:

<filedata modifier> LIBMAINTDIR = <disk file name>

Note: When you specify LIBMAINTDIR=TRUE, library maintenance writes the tape

with ANSI87 labels.

Any attempt to purge a library maintenance tape for which there is a tape directory disk

file resident on the DL LIBMAINTDIR disk family requires approval by the operator. When

library maintenance or any other program overwrites a library maintenance tape for which

there is a tape directory disk file resident on the DL LIBMAINTDIR disk family the system

automatically removes that LIBMAINTDIR file.

LOCATECAPABLE

Set the LOCATECAPABLE attribute to ON to indicate that the file requires a tape drive

capable of processing the READ POSITION and LOCATE BLOCK ID tape commands for

fast tape access.

If the assigned tape drive is locate capable, then library maintenance automatically takes

advantage of this feature to do high-speed spacing in the following situations:

• COMPARE Option

Library maintenance uses the LOCATE BLOCK ID tape command to backspace to

compare the file. If you receive a RECOPY REQUIRED message and respond “OK,”

library maintenance uses LOCATE BLOCK ID to backspace to the beginning of that

file to recopy the file. If you respond with “OF,” the file is erased.

• ARCHIVE Directory for Destination Tapes

For a tape that is locate capable, library maintenance stores the BLOCK ID of the

start of each file it copies in the SYSTEM/ARCHIVE directory. If you specify

LIBMAINTDIR = TRUE, library maintenance also stores BLOCK ID information in the

LIBMAINTDIR directory.

• ARCHIVE Directory for Source Tapes

If the original tape was created on a locate capable tape drive, then library

maintenance uses the LOCATE BLOCK ID information found in the ARCHIVE

directory to rapidly space up to each of the files to be copied.

Note: If you intend to add files to the tape later by specifying LIBMAINTAPPEND =

TOEND, then specify LOCATECAPABLE = ON to get the correct type of tape unit.

Archive Subsystem

6–32 8600 1047–506

OFFSITE

When you specify OFFSITE for a tape destination, library maintenance updates the

onsite/offsite status of that tape in the volume library or in the volume directory.

If library maintenance does not successfully copy a file to a destination tape, it purges

the tape and does not update the onsite/offsite status for the tape.

If library maintenance successfully copies the files and OFFSITE is TRUE, then, it marks

the archive entries for files copied to that tape as “offsite.” When library maintenance

closes the tape, it updates the entry for the tape in the volume library or in the volume

directory to indicate that the volume or volumes are “offsite.” If library maintenance

successfully copies the files and OFFSITE is false, then, when library maintenance closes

the tape, it updates the entry for the tape in the volume library or the volume directory to

indicate that the volume or volumes are “onsite.”

Note: Library maintenance performs these actions only when the tape volume is listed

in either the Volume Library, at sites that use the OP + CATALOGING option, or the

Volume Directory, at sites that use the SECOPT TAPECHECK = AUTOMATIC option.

SAVEFACTOR

Indicates the expiration date of a tape volume in terms of the number of days past the

creation date. The default value for archive and library maintenance tapes is 30 days.

When an ARCHIVE backup, ARCHIVE ROLLOUT, or ARCHIVE MERGE request makes a

backup copy of a file that already has four backup copies, the system replaces the

backup copy that has the earliest expiration date. If the expiration dates are the same,

the system replaces the backup copy that has the earliest creation date.

SECURITYGUARD

Identifies the guard file to be invoked for the tape volume if the SECURITYTYPE attribute

is assigned a value of GUARDED or CONTROLLED. The default value is a null string (" ").

For more information about guard files, refer to the Security Features Guide.

Note: This attribute applies only to installations running the Security Accountability

Facility package or the InfoGuard security enhancement software.

SECURITYTYPE

Identifies the tape volume security type. This attribute can have a value of PRIVATE

(default), PUBLIC, GUARDED, or CONTROLLED. PRIVATE tape volumes can be

accessed or overwritten only by their owners and privileged users. PUBLIC tape volumes

can be accessed by tasks with any usercode, as limited by the setting of the

SECURITYUSE attribute. The security of GUARDED and CONTROLLED tape volumes is

determined by the guard file referenced by the SECURITYGUARD attribute.

Note: This attribute applies only to installations running the Security Accountability

Facility package or the InfoGuard security enhancement software.

Archive Subsystem

8600 1047–506 6–33

SECURITYUSE

Specifies how a tape volume that is to be protected by the SECURITYTYPE attribute can

be accessed by nonprivileged users using nonprivileged programs.

Note: This attribute applies only to installations running the Security Accountability

Facility package or the InfoGuard security enhancement software.

SERIALNO

Identifies the specific tape volumes to be used when copying files. This attribute does

not have a default value. For more information, refer to “Serial Number Assignment” in

Section 5.

SCRATCHPOOL

Identifies the scratch pool from which the tape is retrieved for archiving. The scratch pool

name can be a 17-character identifier. This attribute does not contain a default value.

USECATALOG

If true, indicates that a listed tape in the volume library should be used. The archive

procedure uses this attribute at cataloging installations only.

Archive Subsystem

6–34 8600 1047–506

ARCHIVE CD Volume

ÄÄ<CD name>ÄÄ<archive CD volume attribute list>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The volume name specifies the name of the destination CD-ROM volumes.

You can optionally specify one SERIALNO for a CD-ROM destination. If you do include a

serial number, the system uses that serial number for all CDCOPIES it creates and for

any extra CD-ROM volumes it needs to contain all the files being copied. If you do not

include a serial number, then the system uses a serial number of the form YYMMDD (a

6-digit number in which the first two digits correspond to the year, the next two digits

correspond to the month, and the last two digits correspond to the day of the month).

For example, an archive backup to CD-ROM done on February 10, 2001 would use the

serial number 010210 if you did not specify a serial number in the ARCHIVE backup

statement.

Normally tape volumes have unique serial numbers. Therefore, when an ARCHIVE

RESTORE process issues a "NO FILE" RSVP message for a tape, including the serial

number, it is relatively easy for the operator to locate and load the requested volume.

When making an archive backup to a CD-ROM volume, try to pick a volume name and

optionally a serial number to help you locate the correct CD-ROM volume during an

ARCHIVE RESTORE. When restoring from a CD-ROM volume, the "NO FAMILY" RSVP

message includes the volume name, the serial number, and the volume sequence

number (which is displayed as the family index number).

NO FAMILY <volume name> (CD) [<serial number>]

# <family index number>

The volume sequence number identifies which volume is needed in cases where the

ARCHIVE backup process filled up one CD-ROM volume and continued copying files to

one or more additional CD-ROM volumes.

Note: Unlike tape volumes, you cannot put a serial number on a CD-ROM volume in

advance. When you include a serial number in an ARCHIVE backup statement for a

CD-ROM volume, the system gives all the CD-ROM volumes it copies files to the same

serial number.

Example

The following example causes the system to back up all the files on PACK to one or

more CD-ROM volumes

ARCHIVE FULL & REPORT *= FROM PACK TO PACK20010510 (CD);

Archive Subsystem

8600 1047–506 6–35

ARCHIVE CD Volume Attribute List

ÄÄ ( ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄ CD ÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ KIND ÄÄ = ÄÙ ÀÄ CDROM ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄ , ÄÂÄ CDCOPIES ÄÄ = ÄÄ<integer expression>ÄÄÄÂÄÁÄ ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ OFFSITE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<Boolean expression>ÄÄÄÄÄÄÄÄ´

ÃÄ PACKETWRITE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<Boolean expression>ÄÄÄÄ´

ÃÄ SAVEFACTOR ÄÄ = ÄÄ<integer expression>Ä´

ÀÄ SERIALNO ÄÄ = ÄÄ<serial number>ÄÄÄÄÄÄÄÄÙ

Explanation

You can specify the following attributes for the archive tape volume attribute list:

• CDCOPIES

• MULTIVOLUME

• OFFSITE

• PACKETWRITE

• SAVEFACTOR

• SERIALNO

CDCOPIES

The CDCOPIES value specifies how many duplicate CD-ROM volumes should be

created. A value of 2 indicates one original and one duplicate. A value of 3 indicates one

original and two duplicates. Do not get CDCOPIES mixed up with the extra CD-ROM

volumes the archive process creates when the files it is copying overflows the first

volume. The archive process creates duplicates of each overflow volume according to

the value of CDCOPIES.

MULTIVOLUME

If you specify the MULTIVOLUME attribute, the WFL compiler issues a syntax error. The

archive system automatically sets the MULTIVOLUME attribute.

OFFSITE

If you set the OFFSITE attribute to TRUE, the system marks the backup records it

creates as referring to an offsite volume. During an archive restore, the system does not

use volumes marked as offsite unless there are no better alternatives.

Archive Subsystem

6–36 8600 1047–506

PACKETWRITE

The PACKETWRITE attribute determines whether the archive process writes the

CD-ROM volumes in track-at-once mode or packet mode. Track-at-once mode (the

default) is more efficient, and the resulting CD-ROM volumes can be read by CD-ROM

and CD-R units. Packet mode avoids possible buffer underrun I/O errors during the write

process and so is safer, but packet mode CD-ROM volumes can only be read by CD-R

units.

SAVEFACTOR

The SAVEFACTOR attribute indicates the expiration date of the CD-ROM volume in

terms of the number of days past the creation date. The default value for archive

CD-ROM volumes is 30 days.

When an ARCHIVE backup, ARCHIVE ROLLOUT, or ARCHIVE MERGE request makes a

backup copy of a file that already has 4 backup copies, the system replaces the backup

copy that has the earliest expiration date. If the expiration dates are the same, the

system replaces the backup copy that has the earliest creation date.

SERIALNO

You can optionally specify one serial number. The system uses that serial number for

each of the CD-ROM volumes it creates during the backup process. If you do not specify

a serial number the system gives the output CD-ROM volumes a serial number of the

form YYMMDD, where the first two digits indicate the year, the next to digits indicate

the month, and the last two digits indicate the day of the month.

Archive Subsystem

8600 1047–506 6–37

ARCHIVE Task Equation List

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ; ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ <task attribute assignment> ÄÂÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <library equation> ÄÄÄÄÄÄÄÄÄÄÙ

Explanation

The following table describes the archive task equation list.

Name Description

<task attribute

assignment>

Assigns task attributes to the ARCHIVE statement. For a

complete explanation of task attribute assignments, refer to

Section 5 of this manual.

<library equation> Changes the attributes of libraries. The archive subsystem uses

library equation to change the selector library. For more

information, refer to Section 5, “Library Equation.”

TASKSTRING assignment

You can set TASKSTRING to specify the disk family or families that archive backup

requests should use as temporary storage when copying to a CD-ROM volume. If you

specify the following, then the archive backup system stores the temporary CDIMAGE

disk file on that disk family:

TASKSTRING = "FAMILYNAME= <family name>"

If you specify the following, the archive backup system starts with the first family in the

list:

TASKSTRING = "FAMILYNAME= (<family name>, <family name>, ... <family name>)

If you have installed a custom ARCHIVESUPPORT library that uses the SFORKV

multitasking feature then tasks rotate through the list of family names you specify.

For information about the multitasking feature, refer to the MCP System Interfaces

Programming Reference Manual.

Archive Subsystem

6–38 8600 1047–506

ARCHIVE MERGE Statement

ÄÄ ARCHIVE MERGE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ FROM ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ <archive options> ÄÙ

ëÄ <archive disk volume> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ TO ÄÄ <archive tape volume> ÄÁÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ <task identifier> ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ; ÄÄ <archive task equation list> ÄÙ

Explanation

The ARCHIVE MERGE statement transfers backup copies of files that reside on one or

more backup tapes to a single tape. If there is insufficient space to merge all requested

backup tape files to one tape, a reel switch condition results and the remaining files are

merged on another tape. This produces a single tape set of merged files.

The primary purpose of this operation is to enable more efficient use of tape resources.

When you merge files to a single backup tape or to a tape set, space is freed on other

tape volumes for other uses.

The ARCHIVE MERGE statement requests as input any file that has been archived to a

backup tape by any ARCHIVE backup statement, ARCHIVE MERGE statement, or

ARCHIVE ROLLOUT statement.

Note: Use of the ARCHIVE MERGE statement usually requires privileged access.

However, a job can run this statement if it was started from an ODT without a usercode.

In any case, this statement affects all tape files that were backed up or rolled out to a

backup tape through the archive subsystem.

As a merge operation executes, it requests as input the backup tape files that were

created by preceding ARCHIVE statements. During the operation, the archive subsystem

prompts you to load the input tapes on the tape drives twice: once while the system

creates the output tape directory, and again when it copies the selected files.

You can use the OF (Optional File) system command to cause the merge operation to

skip an input tape value. You can enter <mix number> OF when the archive subsystem

prompts you to load the input tape. You can use the HI (Cause Exception Event) system

command to check the progress of an ARCHIVE MERGE statement. A command of the

form <mix number> HI displays the number of files already copied and other information.

Example

The following example illustrates how to consolidate archive backup tapes for the family

DISK onto a new backup tape named MERGEDISK:

ARCHIVE MERGE FROM DISK TO MERGEDISK

Archive Subsystem

8600 1047–506 6–39

ARCHIVE PURGE Statement

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ARCHIVE PURGE ÄÁÄÂÄ<long file name constant>ÄÄÄÄÄÄÂÄÁÄ FROM ÄÄÄÄÄÄÄÄë

ÀÄ<long directory name constant>ÄÙ

ëÄ<archive disk volume>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

This statement purges archive backup records from the archive directory without

affecting resident or nonresident files in any way. The ARCHIVE PURGE statement does

not affect catalog backup information.

Purging archive backup records serves to remove only references to backup files. To

remove an actual resident disk file and all archive records associated with it, issue a

REMOVE statement followed by an ARCHIVE PURGE statement. Both statements must

identify the name of the target file. You can also refer to the REMOVE statement with

the DESTROY option that is described later in this section.

If you remove a file, but you do not purge its corresponding archive backup records,

other ARCHIVE statement operations will continue to search for that file. Searches for

disk files that have been removed from disk, but for which archive backup records still

exist, result in NO FILE conditions.

If your installation uses the archive AUTORESTORE feature, the archive subsystem

responds to each NO FILE condition by reloading the missing archived files from tape.

Example

The following example purges the entries for FILE/1 and FILE/2 from the archive

directory for the family MCPMAST:

ARCHIVE PURGE FILE/1, FILE/2 FROM MCPMAST

Archive Subsystem

6–40 8600 1047–506

ARCHIVE RELEASE Statement

ÄÄ ARCHIVE RELEASE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄ <remove list> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ <remove from group> ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÙ

ÀÄ , ÄÄ <remove list> ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ <file name> ÄÄÄÄÄÄÂÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <directory name> ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ <file name> ÄÄÄÄÄÄÂÄÁÄ FROM ÄÄ <family name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <directory name> ÄÙ

Explanation

The ARCHIVE RELEASE statement removes files from disk that are not in use and have

up-to-date archive backup records.

The removed files can be restored by the archive AUTORESTORE feature or the

ARCHIVE RESTORE and ARCHIVE ADDRESTORE statements.

In addition to the ARCHIVE RELEASE statement, see also the REMOVE and REMOVE

DESTROY statements described later in this section.

The first name in a remove list can be a file title or a directory title; that is, it can contain

an ON family name part. Subsequent names in the remove list can only contain an ON

family name part if they contain a string primary as well.

In the remove from group, the FROM clause applies to all the file names and directory

names in that remove from group.

Archive Subsystem

8600 1047–506 6–41

ARCHIVE RESTORE Statement

ÄÄ ARCHIVE ÄÂÄ RESTORE ÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ RESTOREADD ÄÙ ÀÄ <archive options> ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄ¿

ëÄÁÄÂÄ <directory name> ÄÂÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ <file name> ÄÄÄÄÄÄÙ

ëÄ TO ÄÄ <archive disk volume> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ <task identifier> ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ; ÄÄ <archive task equation list> ÄÙ

Explanation

The ARCHIVE RESTORE statement reloads backup copies of disk files to disk. You can

use this statement to recover disk files that have been damaged, lost, or inadvertently

removed from disk. Only backup files that were copied through one of the ARCHIVE

backup statements, the ARCHIVE MERGE statement, or the ARCHIVE ROLLOUT

statement, can be restored to disk through the ARCHIVE RESTORE statement.

Note: WFL includes another statement called simply RESTORE, rather than ARCHIVE

RESTORE. The two statements serve different purposes. The ARCHIVE RESTORE

statement reloads files that have archive backup directory entries. The RESTORE

statement reloads files from any library maintenance tape, regardless of whether or not

the files have archive backup directory entries.

The ARCHIVE RESTORE statement has the following variants, which function differently:

• ARCHIVE RESTORE

This statement reloads selected backup copies of files to disk even if versions of

those files already exist on the destination disk.

• ARCHIVE RESTOREADD

This statement reloads only those selected files for which versions do not already

reside on the destination disk.

With both the ARCHIVE RESTORE and the ARCHIVE RESTOREADD statements, the

archive subsystem selects files by comparing the files you request with records in the

archive directory. The restore and restoreadd processes do not affect the archive

directory in any way. You can remove a restored file and restore it to disk again, even if

an intervening archive backup process has not been performed on that file.

Note: In most installations, you must have privileged access to reload files other than

your own. However, you can reload another user’s files if the job running the RESTORE

or RESTOREADD process runs without a usercode and starts from an ODT.

Archive Subsystem

6–42 8600 1047–506

The archive subsystem usually restores only the most recently written archived files

from the most recently written archive tapes. Under the following circumstances,

however, the archive subsystem restores older versions of files:

• At installations that use the catalog volume library or the volume directory.

• The archive subsystem finds that the contents of a specified backup tape have been

purged or overwritten, or the backup tape has been marked as destroyed or offsite

with a VOLUME DESTROY or VOLUME OFFSITE statement.

• Your installation uses a custom version of the archive support library and that library

selects an older version of a backup tape file for the restore or restoreadd operation.

You can use the HI (Cause Exception Event) system command to check the progress of

an ARCHIVE RESTORE statement. A command of the form <mix number> HI displays

the number of files already copied and other information.

Examples

The following example illustrates how to manually restore an entire family:

ARCHIVE RESTORE = TO USERPACK

The following example shows how to restore only those files that do not already reside

on the disk where the family TESTPACK is located:

ARCHIVE RESTOREADD = TO TESTPACK

Archive Subsystem

8600 1047–506 6–43

ARCHIVE ROLLOUT Statement

ÄÄ ARCHIVE ROLLOUT ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ<archive options>ÄÙ

ëÄÂÄ DRC ÄÄ<int exp>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄë

³ ³ ÚêÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄ¿ ³

³ ÃÄÄÄÄÄÄÂÄÂÄÁÄ (-<usercode>-) ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ³

³ ÀÄ OF ÄÙ ÀÄ ALL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ USERS ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<int exp>ÄÄ SECTORS ÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ALL FILES ÄÄÄÄÄÄÄÄÄÄÙ ³ ÚêÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄ¿ ³

ÃÄÄÄÄÄÄÄÄÄÄÂÄÂÄÁÄÂÄ (-<usercode>-) ÄÂÄÁÄ³

ÀÄ SELECT ÄÙ ³ ÀÄ/1\Ä * ÄÄÄÄÄÄÄÄÄÄÙ ³

ÀÄ ALL ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ USERS ÄÄÄÄÄÄÄÄÄÄÙ

ëÄ FROM ÄÄ<archive disk volume>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÃÄ TO ÄÄ<archive CD-R volume>ÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ TO ÄÄ<archive tape volume>ÄÁÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ<task identifier>ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ; ÄÄ<archive task equation list>ÄÙ

Explanation

This statement moves selected disk files to archive backup tape media. The primary

function of this option is to free disk space for other uses, particularly when resources

are limited.

You can use this option to either

• Specify the amount of disk space (in sectors) you want to make available.

• Specify a percentage of the authorized DRC disk space by which each user’s space

is to be reduced.

Archive Subsystem

6–44 8600 1047–506

DRC Option

You can specify disk space by using the DRC option of the ARCHIVE ROLLOUT

statement. The DRC option is available to you even if your installation does not actively

run the DRC subsystem. This option affects only those users for whom DRC limits are

assigned in the USERDATAFILE.

As each selected file is rolled out to tape, the archive subsystem records the transfer in

the archive directory and the file is removed from the disk. You can use rolled out files as

input to any library maintenance command or statement.

Note: If the archive directory includes references to archived copies of the files that

your rollout operation is requesting, the rollout process removes the resident versions of

the files without recopying those files to tape. Therefore, it is possible to complete a

rollout operation without receiving a system request for a backup tape.

Before the archive statement actually performs a rollout operation, it evaluates files for

possible selection. This process is based on your usercode, or the usercode of the job

that is running the ARCHIVE ROLLOUT statement.

• If you do not list specific usercodes with your ARCHIVE ROLLOUT statement, only

files under the usercode of the job that is running the rollout process are evaluated

for possible selection.

• If the job that is running the ARCHIVE ROLLOUT statement started at an ODT

without a usercode, then only files without a usercode are evaluated for selection.

• If your usercode enables you privileged access and you specify ALL USERS in the

ARCHIVE ROLLOUT statement, all files are evaluated for possible selection.

Specifying SECTORS or Using the DRC Option

You can use the ARCHIVE ROLLOUT statement to make available a particular number of

in-use sectors on a disk family in either of two ways:

• Use the SECTORS option of this statement.

• Invoke the DRC option.

The following discussion describes the differences between these two approaches to

freeing disk space.

In general, using the ARCHIVE ROLLOUT statement on files other than your own

requires privileged access to files.

ARCHIVE ROLLOUT statements that include the SECTORS options do not require that

DRC limits be set in the USERDATAFILE.

If you use the DRC option, the rollout operation affects only the files under usercodes for

which DRC limits are assigned in the USERDATAFILE.

When you use the ARCHIVE ROLLOUT statement to free a specified number of in-use

sectors on a disk family (by using the SECTORS option), the ARCHIVE statement can be

Archive Subsystem

8600 1047–506 6–45

used to copy files to tape and remove files from disk to satisfy your request. If you have

specified more sectors than are already in use under your usercode on the disk family,

the archive subsystem selects all of your files for the rollout operation.

In this case, the operation is executed as if you had specified the ALL FILES option in the

statement.

Checking the Progress of the Rollout

You can use the HI (Cause Exception Event) system command to check the progress of

an ARCHIVE ROLLOUT statement. A command of the form <mix number> HI displays

the number of files already copied and other information.

Examples

The ARCHIVE ROLLOUT statement is used in the following example to free 1000

sectors from files that are under usercode TEMP or DONTCARE:

ARCHIVE ROLLOUT 1000 SECTORS SELECT (TEMP), (DONTCARE) FROM MYPK

The following example moves all files belonging to user MIKEB to MIKESAVE:

ARCHIVE ROLLOUT ALL FILES (MIKEB) FROM DISK TO MIKESAVE

The following example uses the DRC option of the ARCHIVE ROLLOUT statement. If the

DRC authorization for usercode XYZ on PACK is 20000 sectors, then this example rolls

out files belonging to XYZ until that user’s files occupy 18000 sectors or less.

ARCHIVE ROLLOUT DRC 10 (XYZ) FROM PACK

Assignment Statements

6–46 8600 1047–506

Assignment Statements

ÄÄÂÄ <Boolean assignment statement> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <integer assignment statement> Ä´

ÃÄ <real assignment statement> ÄÄÄÄ´

ÃÄ <string assignment statement> ÄÄ´

ÃÄ <file assignment statement> ÄÄÄÄ´

ÀÄ <task assignment statement> ÄÄÄÄÙ

ÄÄ <Boolean identifier> ÄÄ := ÄÄ <Boolean expression> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ <integer identifier> ÄÄ := ÄÄ <integer expression> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ <real identifier> ÄÄ := ÄÄ <real expression> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ <string identifier> ÄÄ := ÄÄ <string expression> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ <file identifier> ÄÄ ( ÄÁÄ <file attribute assignment> ÄÁÄ ) ÄÄÄÄÄÄÄ´

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ <task identifier> ÄÄ ( ÄÁÄÂÄ <task attribute assignment> ÄÂÄÁÄ ) ÄÄÄ´

ÀÄ <file equation> ÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

The assignment statement assigns values to declared variables.

For more information about the file assignment statement, refer to “Using File

Attributes” in Section 5. For more information about the task assignment statement,

refer to “Using Task Variables” in Section 5.

Assignment Statements

8600 1047–506 6–47

Example

The first section of the following example declares variables of type Boolean, integer,

real, string, file, and task. The statements in the next section of the example assign

values to the declared variables.

BOOLEAN B;

INTEGER I;

REAL R;

STRING S;

FILE F;

TASK T;

B:=FILE A/B ON PACK IS RESIDENT;

I:=INTEGER(R);

R:=17.5; S:="ABC"; F(AREASIZE=1008,FLEXIBLE); % File Attribute Assignment

T(PRIORITY=70); % Task Attribute Assignment

BIND Statement

6–48 8600 1047–506

BIND Statement

ÄÄ BIND ÄÄ <object code file title> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄë

ÀÄ [ ÄÄ <task identifier> ÄÄ ] ÄÙ

ëÄÂÄ BINDER ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÀÄ ON ÄÄ <family name> Ä´

ÀÄ WITH ÄÄ <binder title> ÄÄÄÄÄÄÄÄÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ <task identifier> ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ SYNTAX ÄÄÄÄÄÄÄÄ´ ÀÄ <compiler task equation list> ÄÙ

ÃÄ LIBRARY ÄÄÄÄÄÄÄ´

ÃÄ GO ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ LIBRARY ÄÄ GO ÄÙ

ÄÄ <file title> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The BIND statement invokes the Binder to combine object code files.

Binder uses the following sources of input:

• A primary input file titled CARD, which contains directions to the Binder

• A host file titled HOST, which is the object code file to which the subprograms are to

be bound

• Subprogram files, which contain the subprograms to be bound to the host program

For a more detailed explanation and the complete syntax, see “COMPILE or BIND

Statement” later in this section. Refer to the Binder Reference Manual for instructions

regarding using Binder.

Example

The following is an example job that uses the BIND statement:

?BEGIN JOB BIND/RESULT;

BIND COBOL85/EXAMPLE WITH BINDER LIBRARY;

BINDER DATA CARD % This local data specification

HOST IS COBOL85/HOST; % replaces the input file CARD.

USE S1 FOR PROG;

BIND S1 FROM COBOL85/PROG;

? % End Binder data

?END JOB.

CASE Statement

8600 1047–506 6–49

CASE Statement

ÄÄ CASE ÄÄ<case expression>ÄÄ of ÄÄ BEGIN ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ ; ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ëÄÁÄ ( ÄÁÄ<case constant expression>ÄÁÄ ) ÄÄ : ÄÄ<statement>ÄÁÄÄÄÄÄÄÄÄÄë

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÂÄ END ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ; ÄÄ ELSE ÄÄ : ÄÄ<statement>ÄÙ ÀÄ ; ÄÙ

ÄÄÂÄ <integer expression> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <string expression> ÄÄÙ

ÄÄÂÄ <integer constant expression> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <string constant expression> ÄÄÙ

Explanation

The CASE statement provides a way to dynamically select one of several alternative

statements, depending on the value of the case expression.

The case constant expressions, in the parentheses that precede the statements, must

be of the same type as the case expression. In addition, no two case constant

expressions within the same CASE statement can have the same value.

The ELSE specification specifies an action to take if the value of the case expression is

not equal to any of the case constant expressions. If there is no ELSE specification, and

the case expression does not equal any of the case constant expressions, then a fatal

run-time error occurs.

Example

The following is an example job that uses the CASE statement:

?BEGIN JOB CASE/EXAMPLE(STRING DAY);

CLASS=2;

CASE DAY OF

BEGIN

("MONDAY",

"TUESDAY",

"WEDNESDAY",

"THURSDAY"): RUN OBJECT/DAILY/UPDATE;

("FRIDAY"): RUN OBJECT/WEEKLY/UPDATE;

("SATURDAY",

"SUNDAY"): ; % NO RUN NEEDED

ELSE: ABORT "INVALID INPUT STRING:" & DAY;

END;

?END JOB.

CATALOG Statement

6–50 8600 1047–506

CATALOG Statement

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ CATALOG ÄÂÄ ADD ÄÄÄÄÂÄÁÄÂÄ<file name constant>ÄÄÄÄÄÄÂÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÃÄ DELETE Ä´ ÀÄ<directory name constant>ÄÙ

ÀÄ PURGE ÄÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ ( ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄ DISK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ) ÄÙ

ÃÄ KIND ÄÄ = ÄÙ ÃÄ PACK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ TAPE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ GENERATION ÄÄ = ÄÄ<integer constant>ÄÄÄÄÄ´

ÃÄ CYCLE ÄÄ = ÄÄ<integer constant>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ VERSION ÄÄ = ÄÄ<integer constant>ÄÄÄÄÄÄÄÄ´

ÃÄ SERIALNO ÄÄ = ÄÄ<serial number list>ÄÄÄÄÄ´

ÀÄ FAMILYNAME ÄÄ = ÄÄ<family name constant>ÄÙ

Explanation

Note: Cataloging is not supported for files within the permanent directory namespace.

The CATALOG statement applies only to a cataloging system. Cataloging provides an

automated method for locating copies of files that are on disk or tape. Cataloged files can

be stored only on disk or tape that has been entered into the cataloging volume library

with the VOLUME ADD statement. Different copies of a file are referred to as

generations.

For tape, the CATALOG add statement enters the name of a permanent file or directory

into the catalog. For disk, CATALOG ADD marks the requested generation of each of the

requested files as cataloged.

The CATALOG DELETE statement removes all references to the specified generation of

the specified files from the system catalog. If the specified generation is resident on

disk, the statement also marks that file as not cataloged.

The CATALOG PURGE statement removes all the backup file information for all

generations of the specified files. If there is a resident generation on disk, the statement

also marks that file as not cataloged.

The CATALOG DELETE and CATALOG PURGE statements delete only catalog entries;

the resident and backup files are still available but cannot be accessed through the

catalog.

The generation is determined by the integer file attributes GENERATION, CYCLE, and

VERSION, as well as by the time stamp automatically maintained by the system. The

most recent generation is given by a value of 0 for GENERATION or, if GENERATION is

not specified, by the highest value of CYCLE and the highest value of VERSION within

that cycle. For the CATALOG DELETE and CATALOG ADD statements, you can use

these file attributes to identify a specific file generation.

CATALOG Statement

8600 1047–506 6–51

The SERIALNO option is required in either of the following cases:

• If KIND = TAPE

• If KIND = PACK and the family is offline

Family substitution is used if the job or task has an active family specification. Only the

primary family name is used. Refer to “FAMILY Assignment” and “Interrogating

Complex Task Attributes” in Section 5.

Examples

The following are examples of the CATALOG statement:

CATALOG ADD FILEA (KIND=PACK, SERIALNO=123456)

CATALOG DELETE = (KIND=TAPE,VERSION=12,CYCLE=5)

CATALOG PURGE FILEA,FILEB(KIND=PACK)

CHANGE Statement

6–52 8600 1047–506

CHANGE Statement

ÄÄ CHANGE ÄÂÄ<change list>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ <change from group> ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ , ÄÄ <change list> ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ <long file title> ÄÄ TO ÄÄ <long file name> ÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄÄÄ´

ÀÄ <long directory title> ÄÄ TO ÄÄ <long directory name> ÄÙ

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄÁÄÂÄ <long file name> ÄÄ TO ÄÄ <long file name> ÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄÄÄÄÄë

ÀÄ <long directory name> ÄÄ TO ÄÄ <long directory name> ÄÙ

ëÄ FROM ÄÄ <family name> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

The CHANGE statement changes the names of files on disk.

Conflicting File Name

If you specify a file name and a file already exists with that file name, the existing file

with the same name is removed before the file name specified is changed to the new file

name.

Conflicting Directory Change Requests

Because directory change requests are processed in groups of files, two simultaneous

change requests that affect the same set of files produce unpredictable results. For

example, simultaneous CHANGE A/= TO B/= and CHANGE B/= TO A/= statements,

where both directories A/= and B/= exist with nonconflicting file names, can result in all

files in directory A/=, all files in directory B/=, or with the files shared between the two

directories.

Directory Changes

If you specify a directory, the names of the files in that directory are changed. If the new

directory name already exists, the files are added to that directory, and any files that

already belonged to the new directory are not changed. The directories *= and = cannot

be used in the CHANGE statement.

LOCKFILE Attribute

If you use the CHANGE statement to change the name of a file whose LOCKEDFILE file

attribute is set to TRUE, the file name is not changed. The system displays the following

message to indicate that the file name was not changed:

<file name> NOT CHANGED (LOCKEDFILE).

CHANGE Statement

8600 1047–506 6–53

See “ALTER Statement” in this section for more information about changing the

LOCKEDFILE file attribute. For additional information about the LOCKEDFILE file

attribute, refer to the File Attributes Reference Manual.

Change From Group

When you use a “change from” group, the FROM clause applies to all of the file names

and directory names in that “change from” group.

Active Family Specification

Family substitution is used if the job or task has an active family specification. Only the

primary family name is used. For more information on active family specification, refer to

“FAMILY Assignment” and “Interrogating Complex Task Attributes” in Section 5.

Change Privileges

You can use the CHANGE statement to change the name of a file or directory if any one

of the following conditions is true:

• You are a privileged user.

• You are the owner of the file or directory.

• You have write access to the file or directory.

Examples

The CHANGE statement changes the name of file X on DISK to Y:

CHANGE X TO Y;

This statement changes the name of file A/B on USERS to C/D:

CHANGE A/B ON USERS TO C/D;

This statement changes the names of all the files under the directory A/= on PACK to

B/= on PACK:

S1:="A/=";

S2:="B/=";

CHANGE #S1 ON PACK TO #S2;

This statement changes the name of file X on MYPACK to Y, changes the name of file

X/X on MYPACK to Y/Y, changes the name of file XX on PACK to YY, and changes the

name of file Z on DISK to ZZ:

CHANGE X TO Y, X/X TO Y/Y FROM MYPACK,

XX TO YY FROM PACK,

Z TO ZZ;

COMPILE or BIND Statement

6–54 8600 1047–506

COMPILE or BIND Statement

ÄÄÂÄ COMPILE ÄÂÄ<object code file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ BIND ÄÄÄÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ<task identifier>ÄÄ ] ÄÙ

ÄÄÂÄ<compiler name>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÀÄ ON ÄÄ<family name>Ä´

ÀÄ WITH ÄÄ<compiler title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ<task identifier>ÄÄ ] ÄÙ ÃÄ SYNTAX ÄÄÄÄÄÄÄÄ´

ÃÄ LIBRARY ÄÄÄÄÄÄÄ´

ÃÄ GO ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ LIBRARY GO ÄÄÄÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄÄÄÄÄÄ<compiler task equation list>ÄÙ

ÄÄ<file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄÂÄ ALGOL ÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ BINDER ÄÄÄÄ´

ÃÄ CC ÄÄÄÄÄÄÄÄ´

ÃÄ C ÄÄÄÄÄÄÄÄÄ´

ÃÄ COBOL74 ÄÄÄ´

ÃÄ COBOL85 ÄÄÄ´

ÃÄ DCALGOL ÄÄÄ´

ÃÄ DMALGOL ÄÄÄ´

ÃÄ FORTRAN77 Ä´

ÃÄ MODULA2 ÄÄÄ´

ÃÄ NDLII ÄÄÄÄÄ´

ÃÄ NEWP ÄÄÄÄÄÄ´

ÃÄ PASCAL ÄÄÄÄ´

ÃÄ RPG ÄÄÄÄÄÄÄ´

ÀÄ SORT ÄÄÄÄÄÄÙ

Explanation

The COMPILE statement initiates compilation of a program, and optionally can also

cause the resulting object code file to be executed.

COMPILE or BIND Statement

8600 1047–506 6–55

Naming the Object Code File

The object code file title construct specifies the name of the object code file that results

from the compilation. The source file is assumed to be a card reader file named CARD.

However, a file equation can be included in the compiler task equation list to cause a file

with a different title or kind to be used instead.

Example

The following example will cause a source file titled COUNTER to be compiled. The

resulting object code file will be titled OBJECT/COUNTER.

COMPILE OBJECT/COUNTER WITH PASCAL LIBRARY;

COMPILER FILE CARD(TITLE = COUNTER, KIND = DISK);

Choosing a Compiler

The name of the compiler to be used is usually the same as the name of the language

that the program is written in. The phrase WITH compiler title specifies the name of the

compiler desired, as in the previous example which uses the Pascal compiler.

The prefix SYSTEM/ is always assumed to precede the first node of the compiler title

(after any usercode or asterisk (*)). Thus the prefix SYSTEM/ should not be explicitly

specified. The compiler title has the same form as a file title, except that the maximum

number of nodes is 11.

Examples

The following statement uses SYSTEM/ALGOL:

COMPILE OBJECT/X WITH ALGOL LIBRARY;

The following statement uses (SITE)SYSTEM/COBOL74 ON PACK:

COMPILE OBJECT/X WITH (SITE)COBOL74 ON PACK LIBRARY;

If the specified compiler is not a compiler object code file, the job is discontinued.

If the compiler is one of the standard compilers recognized by WFL, the word WITH can

be omitted, and the compiler name can be entered by itself. The characters C or CC are

synonyms for the C language compiler name.

COMPILE or BIND Statement

6–56 8600 1047–506

Binding

The Binder is used to combine two or more object code files into one object code file.

The object code files are the result of successful compilations of source files. To use the

Binder, include the word BIND instead of COMPILE at the start of the COMPILE or BIND

statement, and use as the compiler name. Binder uses the following sources of input:

• A primary input file titled CARD, which contains directions to the Binder

• A host file titled HOST, which is the object code file to which the subprograms are to

be bound

• Subprogram files, which contain the subprograms to be bound to the host program

Example

The following is an example of a bind statement:

?BEGIN JOB BIND/RESULT;

BIND COBOL85/EXAMPLE WITH BINDER LIBRARY;

BINDER DATA CARD % This local data specification

HOST IS COBOL85/HOST; % replaces the input file CARD.

USE S1 FOR PROG;

BIND S1 FROM COBOL85/PROG;

? % End Binder data

?END JOB.

Refer to the Binder Reference Manual for instructions regarding using the Binder

program.

Object Code File Disposition

A phrase can be included to indicate the disposition of the object code file. The

disposition determines whether the object code file is saved or executed. If no

disposition is included in the COMPILE statement, a disposition of GO is assumed.

The following are the possible dispositions and their meanings.

Disposition Definition

GO The object code file is executed but not saved. If there are syntax errors,

execution does not occur.

LIBRARY The object code file is saved but not executed. If there are syntax errors,

the object code file is not saved.

LIBRARY GO The object code file is saved and also executed. If there are syntax

errors, the object code file is not saved or executed.

SYNTAX The object code file is not saved and not executed. This disposition is

used to check the program for syntax errors only.

COMPILE or BIND Statement

8600 1047–506 6–57

Task Variables

Task variables can be included in the COMPILE statement in either of two places. The

position determines whether a task variable is associated with the compilation or the

execution of the program. The same task variable cannot be assigned to both the

compilation and execution, because these are separate tasks.

A task identifier included after the object code file title associates a task variable with the

execution of the object code file. This task identifier is not used if the disposition of the

COMPILE statement does not cause the object code file to be executed. Because this is

usually a programming error, a warning is given to indicate that the task identifier is not

used.

A task identifier included after the compiler name or compiler title associates a task

variable with the compilation of the object code file.

The task state of the task variables included in the COMPILE statement can be

interrogated later to find out if the compilation and execution of the program were

successful.

Example

The following example includes task variables with COMPILE statements:

COMPILE (RAS)OBJECT/ITAL [TRUN] WITH ALGOL [TCOMP] LIBRARY GO;

COMPILER FILE CARD (TITLE = (RAS)ITAL, KIND = DISK);

IF TCOMP ISNT COMPILEDOK THEN

ABORT "UNSUCCESSFUL COMPILE OF OBJECT/ITAL";

IF TRUN ISNT COMPLETEDOK THEN

ABORT "RUN-TIME ERROR IN OBJECT/ITAL";

COMPILE or BIND Statement

6–58 8600 1047–506

Compiler Task Equation List

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ ; ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄ<task attribute assignment>ÄÂÄÁÄÙ

ÃÄ COMPILER ÄÄÄÄÄÄ´ ÃÄ<file equation>ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<compiler name>ÄÙ ÃÄ<library equation>ÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<database equation>ÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ ; ÄÂÄÁÄ<compiler data spec>ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

³ ÀÄÁÄ<local data specification>ÄÁÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ<local data specification>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄÂÄ COMPILER ÄÄÄÄÄÄÄÄÂÄ <local data specification> ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <compiler name> ÄÙ

Explanation

A compiler task equation list specifies task equations for use either during compilation or

during execution of a program. Task attribute assignments, file equations, library

equations, database equations, and local data specifications are all defined in Section 5,

“Task Initiation.”

COMPILE or BIND Statement

8600 1047–506 6–59

File, Library, and Database Equations and Task Attributes

Task attributes, file equations, library equations, and database equations are preceded by

the word COMPILER or a compiler name if they are to be applied to the compilation.

Otherwise, they are permanently attached to the resulting object code file. These values

are assigned to the task whenever the compiled program is executed, unless the

attribute values are overridden by run-time task equations.

The MODIFY statement permits task attributes, file equations, library equations, and

database equations that are compiled into an executable object code file to be added to

or changed, without recompiling the source file. For further information, refer to the

description of the MODIFY statement provided later in this section.

Task attributes, file equations, library equations, and database equations that apply to the

compilation can be mixed with ones that apply to the object code file in any order.

All expressions in task attribute assignments and file attribute assignments for the

program are evaluated prior to compilation. The values obtained are stored in the object

code file as if they had been specified as constants.

Typically, the source file to be used by the compiler is specified by a file equation. For an

example, see “Naming the Object Code File” earlier in this section.

Examples

File equations that change the attributes of the object code file are enabled, but most are

overridden by the compiler and have no effect. However, the security attributes of the

object code file can be set through a file equation, as in the following example:

COMPILE OBJECT/TEST WITH ALGOL LIBRARY;

COMPILER FILE CODE (SECURITYTYPE=PUBLIC,SECURITYUSE=IN);

The resulting object code file has a security of PUBLIC IN. The same effect can be

achieved by using the SECURITY statement to change the security of the object code file

after it is compiled.

Global file equation of the object code file produced by the compiler is not permitted. For

example, if the following statement is specified, a syntax error is given:

COMPILE OBJECT/TEST WITH ALGOL;

COMPILER FILE CODE:=GLOBALFILE; % Illegal syntax

COMPILE or BIND Statement

6–60 8600 1047–506

Local Data Specifications

Local data specifications in a COMPILE or BIND statement are applied either to the

compilation or the resulting object code file, according to the following rules:

• A local data specification that is to be applied to the compilation must be preceded

by the word COMPILER or a compiler name.

• All the local data specifications to be applied to the compilation must precede all the

local data specifications to be applied to the execution of the object code file.

Example

Local data specifications can be applied to the compilation to replace input files used by

the compiler. In the following example, a local data specification takes the place of the

CARD file:

COMPILE OBJECT/RUNNER WITH ALGOL LIBRARY GO;

COMPILER FILE TAPE (TITLE = RUNNER/B);

COMPILER DATA CARD

? % End data CARD

Local data specifications can be applied to the execution of the object code file to replace

input files that would normally be read by the program at run time.

Local data specifications that follow a COMPILE or BIND statement are reread if the

COMPILE or BIND statement is executed more than once.

Run-Time Overriding of Compiler Task Equation

The following example shows how task equations set for a program at compile time can

be overridden at run time:

COMPILE OBJECT/X WITH ALGOL LIBRARY;

COMPILER FILE CARD (TITLE=X,KIND=DISK);

ALGOL PRIORITY=50; % Sets priority of ALGOL compilation.

PRIORITY=60; % Sets priority in object code file X.

RUN OBJECT/X; % Runs at priority 60.

RUN OBJECT/X;

PRIORITY=70; % Overrides compiled-in priority

% and runs at priority 70.

Another example of interaction between compile-time and run-time task equations

appears under “OPTION Assignment” in Section 5.

COMPILE or BIND Statement

8600 1047–506 6–61

COMPILE and BIND Statements

The following example illustrates several COMPILE and BIND statements:

COMPILE X/Y WITH COBOL85 LIBRARY GO;

COBOL85 FILE CARD(TITLE = C/D, KIND = DISK);

COBOL85 PRIORITY = 55;

FILE F(TITLE=Y/Z);

COMPILE A WITH C SYNTAX;

COMPILE X ALGOL;

COMPILE B WITH COBOL85 ON PACK GO;

BIND X/Y WITH BINDER LIBRARY GO;

COMPILE A/B WITH COBOL85 LIBRARY;

COMPILER PUNCHLIMIT = 100;

COMPILER PRINTLIMIT = 130;

COMPILER DATA CARD

? % End of CARD data

Compound Statement

6–62 8600 1047–506

Compound Statement

ÄÄ BEGIN ÄÄ <statement list> ÄÄ END ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Explanation

A compound statement groups one or more statements as a logical entity. Refer to

Section 3, “Job Structure,” for the syntax and explanation of a statement list.

Example

The following is an example job that uses the compound statement:

IF T IS COMPLETEDOK THEN

BEGIN

RUN X;

RUN Y;

END

ELSE

BEGIN

COPY T/INPUT AS T/INPUT/SAVE;

ABORT;

END;

COPY or ADD Statement

8600 1047–506 6–63

COPY or ADD Statement

ÄÂÄ COPY ÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ ADD ÄÄÙ ³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´ ³

ÀÄÁÄÂÄ & ÄÄÄÂÄÂÄÄ/1\ÄÄÄ BECOMEOWNER ÄÄÄÂÄÁÄÙ

ÀÄ AND ÄÙ ÃÄÄ/1\ÄÄÂÄ CATALOG ÄÄÄÄÄÄ´

³ ÀÄ BACKUP ÄÄÄÄÄÄÄ´

ÃÄÄ/1\ÄÄÂÄ COMPARE ÄÄÄÄÄÄ´

³ ÀÄ VERIFY ÄÄÄÄÄÄÄ´

ÃÄÄ/1\ÄÄÂÄ DSONERROR ÄÄÄÄ´

³ ÀÄ WAITONERROR ÄÄ´

ÃÄÄ/1\ÄÄÄ PROPOGATEÄÄÄÄÄÄ´

ÃÄÄ/1\ ÄÄ REMOVE ÄÄÄÄÄÄÄÄ´

ÃÄÄ/1\ÄÄÄ REPORT ÄÄÄÄÄÄÄÄ´

ÀÄÄ/1\ÄÄÄ SKIPEXCLUSIVE ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄ [ ÄÁÄÂÄÄ/1\ÄÄÄ FROMSTART ÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ] ÄÙ

ÀÄÄ/1\ÄÄÄ <transfer service> ÄÙ

ÚêÄÄÄÄÄÄ , ÄÄÄÄÄÄ¿

ëÄÁÄ<copy request>ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

ÀÄ [ ÄÄ<task identifier>ÄÄ ] ÄÙ

ëÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ ; ÄÄ<task attribute assignment>ÄÁÄÙ

Explanation

The following text describe the various components of the COPY or ADD statement. The

information is organized according to its frequency of use and importance.

The COPY statement copies disk files from disks, tapes, or CD-ROMs to disks, tapes, or

CD-ROMs. Some of the uses of the COPY statement are as follows:

• Copying disk files onto tape or CD-ROM volumes or onto other disk families for

safety backup. You can also selectively restore some or all of these files back to disk.

• Copying disk files from one disk family to another.

• Copying new software and disk files from tape or CD-ROM volumes received from

Unisys and other installations to your disks, or copying files to tape or CD-ROM

volumes for transfer to other installations.

• Copying disk files from one host system to another within a network.

• Copying CD-ROM images to write-once CD-ROMs.

The ADD statement, like the COPY statement, copies disk files between disks and

tapes. The ADD statement has the following effects based on the specified destination:

• For a disk destination, it copies only those files that are not already resident on the

specified destination disk.

• For a tape, it is equivalent to a COPY statement with a tape destination. If there were

any files on the destination tape, they are overwritten. The ADD statement copies all

the available requested files to the destination tape or CD-ROM volume.

COPY or ADD Statement

6–64 8600 1047–506

Note: The ADD statement is not valid for CD-ROM volumes.

The ADD statement is particularly useful for adding a directory of files to a disk where

some of the files are already resident and are to be preserved.

See also the MOVE statement, described later in this section, for further information

regarding moving files from one disk to another. Refer to the RESTORE statement for

information regarding copying files from tape to disk.

For all of the following sub-sections, unless otherwise mentioned, explanations about the

COPY statement also apply to the ADD statement.

Special Code for Streamer Tapes

When you copy files from disk to certain tapes, the archive backup process uses special

code to accelerate the copy process to streamer tapes—if all of the following conditions

are met:

• All files to be copied are copied from disk. No files are copied from tape.

• There is one destination only, and the destination is to tape.

• The destination tape unit is one of the following:

IOM Systems

− 2145–01 and 2145–03 tape units

EMS Systems

− 2145–01, 2145–02, and 2145–03 tape units

− B9498 Cipher Streamer tape units

• You do not specify any of the following options:

− & CATALOG

− & DSONERROR

− & WAITONERROR

− & VERIFY

− & REPORT

Note: You can specify the options & COMPARE and & BACKUP.

COPY or ADD Statement

8600 1047–506 6–65

Using Task Variables

The task identifier construct is used to assign a task variable to a COPY statement. The

TASKVALUE attribute can be tested to determine the success or failure of the copy.

When the value of the TASKVALUE attribute is 0, all requests were satisfied, possibly

with retries. When the value of the TASKVALUE attribute is not 0, one or more files were

not copied. A nonzero value is also returned if the copy is discontinued, or in the case of

an RSVP condition, if the failing action is not retried successfully.

Task Attributes

The task attribute assignment construct is used to assign task attributes to the COPY

statement. Task attributes are used to monitor and control the execution of tasks.

For further information regarding task attributes, refer to “Task Attributes” in Section 5.

For more information regarding task attribute assignments, refer to “Task Attribute

Assignment” in Section 5.

Copying Files

When you copy files involving disks, tapes, or CD-ROMs on the local host (that is, the

COPY statement does not include any HOSTNAME specifications), the copy process is

done by the internal system program called *LIBRARY/MAINTENANCE which is

described in the following section. When you copy files involving disks, tapes, or

CD-ROMs on other host systems, the copy process is handled by a file transfer service.

The COPY statement can copy files from the following types of media:

• Disks

• Tapes in library maintenance format

• CD-ROMs in library maintenance format

The COPY statement can copy files to the following types of media:

• Disks

• Tapes

• CD-ROMs

Note: The COPY statement cannot copy files from tapes that were written by

programs other than library maintenance, or from CD-ROMs that are not in library

maintenance format. Disks do not have this restriction.

When the COPY or ADD statement operates on a file with a FILEKIND of FIFO, and you

either copy or add files within the same host or you copy or add files using the NFT file

transfer service, then a description of the FIFO is copied. However, any queued data is

not copied.

When the COPY or ADD statement operates on a file with a FILEKIND of FIFO, and the

statement uses other file transfer services such as Host Services, then the FIFO is not

copied and an error occurs.

COPY or ADD Statement

6–66 8600 1047–506

For further information about the features and limitations of the various file transfer

services, see “COPY File Transfer Services” later in this section. Most of the

descriptions of the COPY or ADD statement apply to both library maintenance and file

transfers.

Library Maintenance

Library maintenance refers to the name of the internal system program that performs the

copy process, called *LIBRARY/MAINTENANCE. When you use the COPY statement to

copy a file to tape or CD, the tape or CD-ROM volume to which a file is copied is marked

as a library maintenance tape or CD-ROM.

To copy files to or from ordinary tapes, use the DUMPALL utility. Normal programs

cannot read files directly from tapes that are written using the library maintenance

program or from CD-ROMs in library maintenance format, nor can they create tape or

CD-ROM volumes in library maintenance format.

To list the names of the files on a library maintenance tape or CD-ROM, use the system

FILEDATA utility program or the TDIR system command. See the System Software

Utilities Operations Reference Manual and the System Commands Reference Manual for

descriptions of the DUMPALL and FILEDATA utilities and the TDIR command.

The library maintenance program checks for errors and discrepancies while copying,

comparing, or verifying files. Whenever library maintenance detects an error, it issues an

error message. Errors can cause library maintenance to do one of the following:

• Stop all copying and terminate.

• Stop copying from a particular source or to a particular destination.

• Stop copying a particular file.

• Issue an RSVP message asking if the file should be recopied.

Certain I/O errors or data discrepancies can generate a message that requires an answer

from the operator before continuing, such as whether a given file should be recopied,

copied with errors as a BADFILE, skipped, or whether a tape with a bad copy of a file

should be purged or the file skipped.

The recopy facility is not available when copying to or from quarter-inch cartridge tapes.

COPY or ADD Statement

8600 1047–506 6–67

To check the progress of a COPY or ADD statement, use the HI (Cause Exception Event)

system command. A command of the form <mix number> HI displays the number of

files already copied and other information.

Note: In most cases, library maintenance takes special action whenever you attempt to

copy KEYEDIOII files from disk. Library maintenance waits until the files are no longer

being updated and then blocks usage of the files and any related files, such as audit and

key files, until all the specified files are copied. However, if you use the AX (Accept)

system command on the KEYEDIOII/LIBRARY to set COPYINQONLY to FALSE, library

maintenance immediately copies the KEYEDIOII files. (See the System Commands

Operations Reference Manual for details on the AX command and the KEYEDIOII

Programming Reference Manual for details on the COPYINQONLY runtime parameter.)

Library maintenance takes special action to ensure that the copies of the various files

making up a KEYEDIOII set are consistent with each other. In general, when you copy a

KEYEDIOII file, it is advisable to copy all the related files in the same COPY statement.

To copy a SYSTEMDIRECTORY file, you must specify its file name in full. For example,

the statement COPY *SYSTEMDIRECTORY/= AS SYSDIR/= FROM . . . does not copy a

system directory file but the following statement does:

COPY *SYSTEMDIRECTORY/001 AS SYSDIR/1 FROM

When library maintenance makes a copy of a SYSTEMDIRECTORY file, it erases the

special system file mark from the copy. System directory files with the system file mark

cannot be removed with the WFL REMOVE statement or be renamed with the WFL

CHANGE statement.

To copy a JOBDESC file, which is a file with a FILEKIND attribute value of

JOBDESCFILE, you must specify the file name in full. For example, the statement COPY

*= FROM . . . does not copy a job description file but the following statement does:

COPY *JOBDESC FROM ...

When library maintenance makes a copy of a JOBDESC file, it changes the FILEKIND

attribute value of the copy to DATA.

COPY or ADD Statement

6–68 8600 1047–506

COPY Options

You can specify the following different options in a COPY statement:

• BACKUP

• BECOMEOWNER

• CATALOG

• COMPARE

• DSONERROR

• FROMSTART

• PROPOGATE

• REMOVE

• REPORT

• SKIPEXCLUSIVE

• VERIFY

• WAITONERROR

BACKUP

Description

Places a backup reference in the system catalog directory of the source disk for each

cataloged file that is copied.

Constraints

• Applies only to a cataloging system.

• If you specify AS or ONTO with the BACKUP option, you get a WFL syntax error.

• If you specify a tape source, you get a WFL syntax error.

• You cannot use this option with CD-ROM sources or destinations.

• The source and destination volumes must be listed in the volume library before the

BACKUP option can be used.

• You cannot use this option with FTAM, FTP, NFT or Host Services File Transfer.

BECOMEOWNER

Description

Controls the ownership of the destination directories and files moved within the

permanent directory namespace and controls the ownership of the destination backup

files in the reserved backup directories. This option causes the OWNER attribute to be

set to the usercode of the task performing the operation rather than having the value

copied from the source.

All other attribute values, including those for GROUP and SECURITYMODE, are copied

from the source. If a nonprivileged user issues a COPY or ADD statement without the

BECOMEOWNER option, only the source directories and files already owned by that

user are included.

COPY or ADD Statement

8600 1047–506 6–69

Constraints

• Supported only on ClearPath HMP NX Series systems.

• Applies only within the permanent directory and reserved backup directory

namespaces.

CATALOG

Description

Marks copied files as cataloged files and lists the source versions as backup copies in the

catalog directory for the destination disk.

If you use the Native File Transfer (NFT) Service to transfer the files between hosts, the

source versions are not marked as backup copies at the destination host, but the

destination files are marked as cataloged files.

The source and destination volumes must be listed in the volume library of the applicable

source or destination host before you can use the CATALOG option.

Constraints

• Applies only to a cataloging system.

• If you specify AS or ONTO with the CATALOG option, you get a WFL syntax error.

• If you specify a tape destination, you get a WFL syntax error.

• You cannot specify a CD-ROM destination.

• You cannot use this option with FTAM, FTP, or Host Services File Transfer.

COMPARE

Description

Ensures that the new copies of the file are written correctly.

Ensures that the new copies of the files are readable, and that the data in the files

matches the data in the source files.

Compares the copied file and the original file bit by bit, immediately after the file is

copied.

Gives you a chance to approve a recopy if an error occurs while comparing a file.

Constraints

• Not available for quarter-inch cartridge tapes; use the VERIFY option instead.

• Not available with Open Systems Interconnection (OSI), File Transfer, Access, and

Management (FTAM), Transmission Control Protocol/Internet Protocol (TCP/IP) File

Transfer Protocol (FTP), or Host Services File Transfer (HS).

COPY or ADD Statement

6–70 8600 1047–506

DSONERROR

Description

Causes library maintenance to terminate with a DS response whenever

• A file or directory to be copied is missing, and library maintenance issues a

“<filename> FILE NOT ON <source volume>” message.

• An error prevents a file from being copied to one or more destinations.

• Library maintenance issues a “RECOPY REQUIRED” RSVP, and the operator replies

with DS, FR, or OF.

If a COPY or ADD statement terminates abnormally when the DSONERROR option is

used, library maintenance purges all of the output tapes it is currently copying.

If a COPY or ADD statement terminates abnormally and multivolume output tapes are

being used, library maintenance purges only the current volume.

In the case of multiple output tapes, an error termination causes all destination volumes

to be purged.

Example 1

COPY & DSONERROR F1 TO T1, TO T2;

An error termination causes both T1 and T2 to be purged.

In the case of multiple copy requests, an error termination causes one of the destination

tapes to be purged.

Example 2

COPY & DSONERROR F1 TO T1, F2 TO T2;

An error termination causes either tape T1 or tape T2 to be purged, but not both tapes.

If a COPY or ADD statement with both the BACKUP and DSONERROR options

terminates abnormally, then in addition to purging any output tapes, library maintenance

erases or deletes any catalog backup information for files that refer to the purged tapes.

In the case of multivolume output tapes, library maintenance erases or deletes the

catalog backup information for files that reference any of the volumes in the specified set

of tapes.

Constraints

You cannot use this option with FTAM, FTP, NFT or Host Services File Transfer.

COPY or ADD Statement

8600 1047–506 6–71

FROMSTART

Description

Overrides any file-transfer resumption if the transfer had been previously interrupted, and

instead completely transfers again all of the files, including those already transferred with

the NFT Service before the interruption.

Constraints

This option applies only when NFT is used to transfer files between hosts.

PROPOGATE

Description

Enables copied files and permanent directories to inherit the security of the destination

directory.

Constraints

This option applies only when the destination PROPAGATESECURITYTOFILES or

PROPAGATESECURITYTODIRS attribute of the directory so specifies.

REMOVE

Description

Causes library maintenance to remove files from the source disk being copied. Library

maintenance removes source files even if they are in use by another program.

• If you specify the VERIFY option when copying to tape, library maintenance verifies

the destination tape before removing the source files.

• If you specify the DSONERROR option, library maintenance delays removing the

source files until all the files have been successfully copied.

• If a program updates or replaces a source file before library maintenance removes it,

then library maintenance removes the updated or replaced version of the file.

Constraints

You cannot use this option with tape or CD-ROM sources, with NFT specified, or in any

host to host transfer.

REPORT

Description

Causes library maintenance to print a report of the files it copied and any errors

encountered. When & REPORT is specified, library maintenance does not write “file

copied” messages in the job log or the system sumlog.

COPY or ADD Statement

6–72 8600 1047–506

Constraints

You cannot use this option with FTAM, FTP, NFT or Host Services File Transfer.

SKIPEXCLUSIVE

Description

Causes the system to not copy those files from disk that are opened with

EXCLUSIVE=TRUE or that are KEYEDIOII files marked as being updated.

Constraints

You cannot use this option with FTAM, FTP, or Host Services File Transfer.

VERIFY

Description

Ensures that the new copies of the file are written correctly and readable, and the data in

them is not garbled.

Verifies files by calculating the checksums for those files as they are copied, and

compares those values as follows:

• Disk source

No checksum is calculated for files read from disk. Library maintenance does not

verify files read from disk.

• Disk destination

Library maintenance calculates a checksum for a file as the file is copied to disk. The

verify process re-reads the file from disk when the copy is completed; calculates the

checksum of the new file; then compares that value with the value calculated while

writing the file to disk. If a mismatch or I/O error occurs, library maintenance issues

an error message, and it might issue a recopy RSVP message.

• Tape source

The copy procedure calculates a checksum for the file as it is read from the tape.

That value is compared with the checksum record, at the end of the file, read from

the tape. If the VERIFY option was not specified when the tape was created, there is

no checksum record on the tape and library maintenance issues a warning. If a

mismatch occurs, library maintenance issues an error message; it might also issue

an RSVP message.

COPY or ADD Statement

8600 1047–506 6–73

• Tape destinations

The copy procedure calculates a checksum for each file as the file is written to the

tape. After each file an extra record containing a checksum is written on the tape.

When all the files have been written to the tape, the tape is rewound, and the verify

process starts. The verify procedure reads each file from the tape and calculates a

checksum for the file. If that checksum does not match the checksum on the tape,

or if there are I/O errors while reading from the tape, library maintenance issues an

error message, and it might issue a special RSVP message to check whether the

tape is to be purged or the bad file is to be skipped.

• CD-ROM sources or destinations

Library maintenance does not calculate a checksum when reading from or writing to

CD-ROMs.

Constraints

This option is not available with FTAM, FTP, or Host Services File Transfer.

WAITONERROR

Description

Causes library maintenance to issue an RSVP message whenever an error occurs.

Examples of possible errors include

• Requesting a file or directory that is missing

• Failing an attempt to open a tape

The RSVP message halts library maintenance until the operator or programmer responds

with either OK or DS.

A response of OK causes library maintenance to continue the COPY with other files or

tapes.

A response of DS will terminate the library maintenance program. After investigating the

error which created the RSVP message, you can re-issue the COPY or ADD statement.

Constraints

You cannot use this option with FTAM, FTP, NFT or Host Services File Transfer.

COPY or ADD Statement

6–74 8600 1047–506

COPY Request

ÚêÄÄÄÄÄ , ÄÄÄÄ¿

ÄÄÂÄÁÄ<copy file>ÄÁÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄë

³ ÚêÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ<copy from group>ÄÁÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ , ÄÄ<copy file>ÄÁÄÙ

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄ¿ ³

ÀÄÁÄ/47\Ä TO ÄÄ<destination volume>ÄÁÄÙ

ÄÄÂÄ<univ. file name>ÄÂÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄ´

³ ÀÄ<origin>ÄÙ ÀÄ AS ÄÄ<univ. file name>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ<long dir. name>ÄÂÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄÄÄÄÄÄÄÄ´

³ ÀÄ<origin>ÄÙ ÀÄ AS ÄÄ<long dir. name>ÄÙ ÃÄ<FTP>ÄÄ´

³ ÀÄ<FTAM>Ä´

ÃÄ<long file name>ÄÂÄÄÄÄÄÄÄÄÄÄÂÄ ONTO ÄÄ<long file name>ÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<origin>ÄÙ ³

ÃÄ<long directory name>ÄÂÄÄÄÄÄÄÄÄÄÄÂÄ ONTO ÄÄ<long directory name>ÄÄ´

³ ÀÄ<origin>ÄÙ ³

ÀÄ<tape file number>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ AS ÄÄ<univ. file name>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ONTO ÄÄ<file name>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ÄÄ ORIGIN ÄÄ< volume name>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÚêÄÄÄÄÄ , ÄÄÄÄ¿

ÄÄÁÄ<copy file>ÄÁÄ FROM ÄÄ<source volume>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÄÄ< volume name>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ<source volume attribute list>ÄÙ

ÄÄ < volume name> ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ <destination volume attribute list> ÄÙ

ÄÄ # ÄÄ<integer constant>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

Basic Copy Request

A basic copy request construct consists of a copy file construct or a copy from group

construct that designates the file or files to be copied.

COPY or ADD Statement

8600 1047–506 6–75

COPY FROM

A copy from group includes a FROM source volume phrase that designates from where

the files are to be copied. If you do not specify a FROM source volume construct, the

files are copied from the disk family named DISK.

COPY TO

You can optionally include a TO destination volume phrase that designates where the

files will be copied. If you do not specify a TO destination volume construct, the files are

copied to the disk family named DISK.

Family Substitution

Family substitution occurs for one or more of the source and/or destination disk family

names specified in the COPY statement when either of the following conditions exist:

• The target family name in the FAMILY assignment statement matches the source

and/or destination disk family names specified in the COPY statement.

• You omitted either the FROM source volume or the TO destination volume phrase in

the COPY statement, and the implied family name DISK matches the name DISK in

the FAMILY statement.

Library maintenance never uses the name supplied after OTHERWISE in a family

substitution statement.

COPY Constructs

The copy file, copy from group, source volume, destination volume, and family name

constructs are described in the following material:

Specifies the names of the files or directories to be copied. If you use the AS option,

specifies the names to which the files or directories should be copied. If you do not use

the AS option, the output file names are exactly the same as the input file names. Output

file names might differ from input names. The following conditions also apply when you

use the AS option:

• If you specify a universal file name, the new copy of the file is given the new name

you specify.

• If you specify a directory name, then the new copy of each file copied from that

directory is given the new directory name you specified instead of the old directory

name, and the portion of the file name that follows the old directory name is

retained.

• If you specify a file or directory name, if the copy process runs under a usercode and

you do not include a usercode or an asterisk (*) with the new file name or new

directory name, the new file names will all be prefixed with the usercode under

which the copy process is running. The ONTO option is limited to use with data files

whose integer value of the FILEKIND attribute is greater than or equal to 64.

COPY or ADD Statement

6–76 8600 1047–506

The ONTO option cannot be used for object code files, compilers, or system files. If the

NOCOPYONTO security option is set, then the ONTO option cannot be used for any file.

The NOCOPYONTO option is available only on a system that contains the Security

Accountability Facility package or the InfoGuard security enhancement software.

Enables you to specify one or more source volumes. The source volume applies to the

entire list of file names and directory names in the copy from group construct. It is best

to group files to be copied from the same tape volume into one copy from group

construct, because the tape is rewound for each copy from group construct operation if

the same tape volume is specified more than once.

Specifies the source volume of the files to copy and the destination volume(s) for those

files. If the source or destination volume is not specified, the volume DISK is assumed. If

all the copy file constructs contain an AS name, you do not have to specify a source or

destination volume. If more than one destination volume is specified, all files are copied

at the same time and in the same order, to all destination volumes, thus creating multiple

copies. In addition, you can indicate certain file attributes and tape volume attributes for

files being copied from a source volume or to a destination volume with the source

volume attribute list and destination volume attribute list constructs.

Indicates the name of the volume from which or onto which the files are copied. If the

volume name is DISK or PACK, the default file kind is DISK; otherwise, the default file

kind is TAPE. If # <string primary> is specified for the volume name, the default file kind

is TAPE.

Family substitution is used if the file kind is DISK and the job or task has an active family

specification. Only the primary substitute family name is used by Library Maintenance

and NFT. (Refer to “FAMILY Assignment” and “Interrogating Complex Task Attributes”

in Section 5.)

Specifies the position number of the file on the source tape or source CD-ROM. The

position number of the first file on a tape is 1, and so forth. The <tape file number> must

be a positive integer that is greater than zero (0) and has less than 12 digits (counting

leading zeros). You can use <tape file number> only in NFT file transfer copy statements.

You cannot specify ORIGIN <family name> for a <tape file number>.

COPY or ADD Statement

8600 1047–506 6–77

ORIGIN Clause

When copying from tape, you can use the ORIGIN clause to select those files that were

originally copied to tape from the specified disk family. This can be useful if you

previously copied files with the same file names from different disk families to the same

tape. For example, the following form of the statement copies two versions of

SYSTEM/ALGOL to the SA tape:

COPY SYSTEM/ALGOL FROM PACK, SYSTEM/ALGOL FROM SYS (PACK) TO SA;

You could then retrieve the version of the file that was copied from either one of the disk

families by specifying the disk family name as in the following statement:

COPY SYSTEM/ALGOL ORIGIN SYS FROM SA TO NEWSYS (PACK),

TO SYSTAPE;

You can use ORIGIN in the file list for a FROM clause that refers to a tape source. You

cannot, however, use ORIGIN for disk or CD-ROM sources. You cannot use ORIGIN in

file transfer requests.

You cannot use ORIGIN to select files on tapes if the tapes do not have origin

information. Tapes created before SSR 41.2 and tapes created by the NFT file transfer

service do not have origin information. Any file copied from a tape without origin

information to another tape does not have origin information either. You can use the

FILEDATA TAPEDIR report to check which files on a tape have origin information.

ONTO Clause

Note: The ONTO clause was originally intended for copying data to Installation

Allocated Disk (IAD) files. Because IAD files are no longer supported, there is little

reason to use the ONTO clause.

Disk Destinations

The ONTO clause changes the handling of cases where a file of the requested name

already exists at a disk destination. In such a case, library maintenance

1. Opens the existing disk file at the destination. (If no file of the same name exists at

the destination, library maintenance does not perform the copy.)

2. Copies data from the source file to the existing destination file.

By contrast, when ONTO is not specified, library maintenance normally does the

following:

1. Creates a new file on disk.

2. Copies the data and file attributes from the source file to the new file.

3. Locks the new file into the directory. If a permanent file of the same name already

exists at the destination, the system removes that file when the new file is locked.

COPY or ADD Statement

6–78 8600 1047–506

Tape and CD-ROM Destinations

For tape and CD-ROM destinations, the ONTO clause has no effect. Library

maintenance always writes a new file on the tape or CD-ROM.

Caution

When you use the ONTO clause, the integrity of the copy is not assured. If

library maintenance terminates while copying data onto an existing disk file,

the disk file might be left with some data copied from the source file and

some data leftover from the destination file.

Example

COPY F ONTO OLDF, D/= ONTO OLDDD/= FROM DPMAST(PACK) TO UDDOCS(PACK)

Copies file F from DPMAST family to UDDOCS family. Library maintenance copies the

source F contents onto the existing destination file OLDF ON UDDOCS.

All files are copied in directory D/= from DPMAST family to UDDOCS family. For each

file, if a file of the same name already exists on UDDOCS family, the source file contents

are copied onto the existing destination file.

Restrictions

The WFL compiler returns a syntax error if the ONTO clause is used in a COPY &

BACKUP or a COPY & CATALOG statement.

Library maintenance will not copy a file onto an existing disk file if any of the following

restrictions are violated:

Type of Restriction Details

AREAS, AREASIZE,

FILESTRUCTURE

Values for the source and destination file must match.

EOFBITS, EOFSEGMENT Values for the source and destination file must match if

the destination file is crunched.

Areas allocated Any allocated area of either the source file or the

destination file must also be allocated in the other.

Destination file usage Cannot be in use by any program.

Destination file characteristics Cannot be

• Object code file

• BADDISK file

• Printer backup file

• File status marked as nonremovable SYSTEMFILE

• Any other special system file

COPY or ADD Statement

8600 1047–506 6–79

Attribute Lists

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ( ÄÁÄÂÄ/1\Ä AUTOUNLOAD ÄÄ = ÄÂÄ ON ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄ ) ÄÄÄÄÄÄÄ´

³ ÃÄ OFF ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ DONTCARE ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä BLOCKSIZE ÄÄ = ÄÄ<integer>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä DOMAINNAME ÄÄ = ÄÄ " ÄÄ<domain name>ÄÄ " Ä´

ÃÄ/1\Ä FAMILYOWNER ÄÄ = ÄÂÄ "" ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<usercode>ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä HOSTNAME ÄÄ = ÄÄ<hostname>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä IPADDRESS ÄÄ = ÄÄ " ÄÄ<IP address>ÄÄ " ÄÄÄ´

ÃÄ/1\ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄ CD ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ KIND ÄÄ = ÄÙ ÃÄ CDROM ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÃÄ DISK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÃÄ PACK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÀÄ TAPE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ KIND ÄÄ = ÄÄ # ÄÄ<string primary>ÄÄÄÄÄÄÄ´

ÃÄ/1\Ä LIBMAINTDIR ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä LOCATECAPABLE ÄÂÄ ON ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ OFF ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ DONTCARE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä OFFSITE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SERIALNO ÄÄ = ÄÄ<serial number list>ÄÄÄÄÄÄ´

ÃÄ/1\Ä UNITNO ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä USERCODE ÄÄ = ÄÄ<log-on info>ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä WINDOWSIZE ÄÄ = ÄÄ<integer expression>ÄÄÄÄ´

ÀÄ/1\Ä YOURNAME ÄÄ = ÄÄ<port number>ÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

COPY or ADD Statement

6–80 8600 1047–506

ÚêÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ , ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿

ÄÄ ( ÄÁÄÂÄ/1\Ä AUTOUNLOAD ÄÄ = ÄÂÄ ON ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÁÄÄÄë

³ ÃÄ OFF ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ DONTCARE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä BLOCKSIZE ÄÄ = ÄÄ<integer>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä CDCOPIES ÄÄ = ÄÄ<integer>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä COMPRESSIONCONTROL ÄÄ = ÄÂÄ USER ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ SYSTEM ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä COMPRESSIONREQUESTED ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>Ä´

ÃÄ/1\Ä CYCLE ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä DENSITY ÄÄ = ÄÂÄ BPI800 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI1250 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI1600 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI6250 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI11000 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ BPI38000 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMT36TRK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTAIT ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTAIT2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDDS ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDDS2 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDDS3 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDLT10 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDLT20 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTDLT35 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ FMTQIC1000 ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ FMTST9840ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä FAMILYINDEX ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä FAMILYOWNER ÄÄ = ÄÂÄ "" ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ * ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ<usercode>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä HOSTNAME ÄÄ = ÄÄ<hostname>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÂÄ CD ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ KIND ÄÄ = ÄÙ ÃÄ CDROM ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÃÄ DISK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÃÄ PACK ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ³ ÀÄ TAPE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ KIND ÄÄ = ÄÄ # ÄÄ<string primary>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä LIBMAINTAPPEND ÄÂÄ NO ÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ TOEND ÄÙ ³

ÃÄ/1\Ä LIBMAINTDIR ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä LOCATECAPABLE ÄÂÄ ON ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÃÄ OFF ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ DONTCARE ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä LOCKEDFILE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä MULTIVOLUME ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä OFFSITE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä PACKETWRITE ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean Exp>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SAVEFACTOR ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\ÄÂÄ SCRATCHPOOL ÄÄ = ÄÄ<scratch pool name>ÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ SERIALNO ÄÄ = ÄÄ<serial number list>ÄÄÄÄÄÄÄÄÄÄÄÄ´

(Continued)

COPY or ADD Statement

8600 1047–506 6–81

ÃÄ/1\Ä SECURITYGUARD ÄÄ = ÄÄ<file title>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SECURITYTYPE ÄÄ = ÄÄ<file mnemonic primary>ÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SECURITYUSE ÄÄ = ÄÄ<file mnemonic primary>ÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SENSITIVEDATA ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä SINGLEUNIT ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä UNITNO ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä USECATALOG ÄÄ = ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

³ ÀÄ = ÄÄ<Boolean expression>ÄÄÄÄÄÄ´

ÃÄ/1\Ä USERCODE ÄÄ = ÄÄ<log-on info>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä VERSION ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ/1\Ä WINDOWSIZE ÄÄ = ÄÄ<integer expression>ÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ/1\Ä YOURNAME ÄÄ = ÄÄ<port number>ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

ëÄ ) ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

<log-on info>

ÄÄ<log-on usercode>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄ´

ÀÄ / ÄÄ<log-on password>ÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ / ÄÄ<log-on account>ÄÙ

<log-on usercode>

<log-on password>

<log-on account>

ÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÂÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <name constant> ÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÃÄ <interchange name constant> Ä´

ÃÄ # ÄÄ <string parameter> ÄÄÄÄÄ´

ÃÄ " ÄÄ " ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ´

ÀÄ ' ÄÄ ' ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ

Explanation

When you use the COPY statement, you can indicate certain file attributes for files being

copied and certain file attributes for each source volume or destination volume. For more

specific information on an attribute, refer to the File Attributes Reference Manual.

You can specify the following file attributes for either the source volume attribute list or

the destination volume attribute list:

• AUTOUNLOAD

• BLOCKSIZE

• CYCLE

• DOMAINNAME

• FAMILYOWNER

• HOSTNAME

• IPADDRESS

• KIND

• LIBMAINTDIR

• LOCATECAPABLE

• OFFSITE

• SCRATCHPOOL

• SERIALNO

• UNITNO

• USERCODE

• WINDOWSIZE

COPY or ADD Statement

6–82 8600 1047–506

AUTOUNLOAD

Determines whether or not a tape is unloaded when it is released by the system during a

reel switch or a file close operation. If the value is ON, the tape is rewound and unloaded.

If the value is OFF, the tape is not unloaded. If the value is DONTCARE, or if this value is

not specified, the tape behavior is controlled by the setting of the AUTOUNLOAD option

of the MODE (Unit Mode) system command. Refer to the System Operations Guide for

further information. If a reel is switched during a COPY and COMPARE operation,

intermediate reels are not unloaded, regardless of the AUTOUNLOAD value, until the

COMPARE phase is finished.

BLOCKSIZE

Specifies the blocksize in words that library maintenance uses when copying files to or

from disk or tape volume. Library maintenance automatically rounds the value you

specify up to an integer multiple of 900 words. If you specify a value larger than

64800 words, library maintenance uses 64800 instead. If you specify a value greater than

4500 words for a tape destination, then library maintenance automatically uses that

blocksize for all disks involved in the operation.

Using the same block size for the source and all the destinations greatly improves the

performance of the copy task. Using a larger blocksize increases the amount of data that

can be stored on any given tape volume.

Notes:

• Certain magnetic tape devices have limits on the maximum length I/O they can

process. If you specify a block size larger than the limit for a tape device, library

maintenance automatically reduces the blocksize to a valid value for that tape

destination.

• If you do not specify BLOCKSIZE for a tape, library maintenance uses the default

value established by the SYSOPS LMBLOCKSIZE system command; or if the default

is zero (0), library maintenance uses a small default blocksize that it selects for each

tape and disk.

• Whenever you copy from a tape or CD-ROM, library maintenance will use the

BLOCKSIZE that was used when the tape or CD-ROM was created, and ignore the

value that is specified.

COPY or ADD Statement

8600 1047–506 6–83

The following table lists the maximum blocksizes for the specified tape drives.

Tape Drive Name

Density

Maximum Library Maintenance

Blocksize

2145–01, 02, 03 1600, 6250 10800 words

CLU9710-DLT4 FMTDLT10,

FMTDLT20

64800 words

CLU9710-DLT7 FMTDLT10,

FMTDLT20,

FMTDLT35

64800 words

CTS5136 (1/2-inch cartridge) FMT36TRK 42300 words

CTS5136, OST5136,

CTS5236, CLU9710-36T

(1/2-inch cartridge)

FMT36TRK 42300 words

CTS9840 FMTST9840 42300 words

ALP430 FMTDDS,

FMTDDS2,

FMTDDS3

10800 words

ALP920 FMTAIT,

FMTAIT2

64800 words

FIPS 5073 (1/2-inch cartridge) 38000 21600 words

HS8500(C) (8mm) 11000 40500 words

MA15OT(U), QIC1000 1250 10800 words

OST5136 (1/2-inch cartridge) FMT36TRK 42300 words

QIC1000 FMTQIC1000 10800 words

USR5073 (1/2-inch cartridge) 38000 42300 words

USD440 (4mm) 38000 42300 words

In addition to these limits, any tape connected to the system through a “soft” or

“emulated” SCSI DLP has a library maintenance blocksize limit of 10800 words.

Library maintenance automatically limits the blocksize it uses when writing to tape

volumes on these tape units so that it will not exceed their blocksize limits.

Library maintenance complies with these limits even if you specify a SYSOPS

LMBLOCKSIZE that exceeds these limits. If you are going to be copying files to a tape

volume on a unit that does not have limits, but might someday need to be read on a tape

unit that has limits, then you should ensure that library maintenance writes the tape with

a blocksize that can be read on the target tape unit.

COPY or ADD Statement

6–84 8600 1047–506

CYCLE

Designates the specific generation of a tape volume family. This file attribute is used in

conjunction with the VERSION attribute. The default value is 1.

DOMAINNAME

Indicates the domain name of the remote host where the source or destination volume is

located. Can be used for FTP only.

FAMILYOWNER

Indicates the usercode of the owner of a tape volume. If you specify a usercode with the

FAMILYOWNER attribute, the usercode becomes the owner. If you do not use the

FAMILYOWNER attribute or you specify a null string (" "), the usercode of the copy

process is used. If you specify an asterisk (*) with the FAMILYOWNER attribute, the

tape volume becomes a nonusercoded volume.

The FAMILYOWNER attribute can be used only if the InfoGuard security enhancement

software or the Security Accountability Facility package is installed, and the TAPECHECK

option of the SECOPT system command is set to AUTOMATIC. This attribute is ignored

if the SECOPT TAPECHECK attribute is set to NONE.

HOSTNAME

Indicates the host name of the remote host where the source or destination volume is

located. The default value is the name of the local host. The HOSTNAME attribute can be

specified for the source or destination volume to copy files from or to a remote host; or it

can be specified for both source and destination volumes to enable files to be copied

from one foreign host to another.

IPADDRESS

Indicates the numerical designator that uniquely identifies remote host where the source

or destination volume is located.

KIND

Describes the peripheral unit associated with the logical file. The default value is TAPE,

unless the volume name is DISK, PACK, or CD. If you want to indicate the kind of tape to

be used, use the DENSITY attribute.

LIBMAINTDIR

Determines, on destination tapes, whether library maintenance should create a tape

directory disk file on the DL LIBMAINTDIR disk family. The LIBMAINTDIR tape directory

disk file describes the destination tape and the files copied to it. Library maintenance

gives tape directory disk files names of the form LIBMAINTDIR/<tape

name>/<date>/<tape serialno>. It also puts them under the usercode that library

maintenance is running under, or * if there is no usercode.

COPY or ADD Statement

8600 1047–506 6–85

Library maintenance stores the following information in these files:

• Serial numbers of the tapes used

• Names of the files copied to those tapes

• Certain other attributes of those files

You receive a report of the information in tape directory disk files by running the

SYSTEM/FILEDATA utility program using the following syntax:

<filedata modifier> LIBMAINTDIR = <disk file name>

Note: When you specify LIBMAINTDIR = TRUE library maintenance writes the tape

with ANSI87 labels.

On source tapes, if you

• Specify LIBMAINTDIR = FALSE, library maintenance uses the tape directory on the

tape volume itself to determine what files are on the tape.

• Specify LIBMAINTDIR = TRUE on a tape that was originally created with

LIBMAINTDIR = FALSE or without any LIBMAINTDIR specification, library

maintenance uses the directory on the tape to determine what files are on the tape

and where the files are located on the tape.

• Specify LIBMAINTDIR = TRUE on a tape that was originally created with

LIBMAINTDIR = TRUE, library maintenance uses the LIBMAINTDIR disk file instead

of the directory on the tape to determine what files are on the tape and where the

files are located on the tape.

• Do not specify LIBMAINTDIR on a tape that was originally created with

LIBMAINTDIR = TRUE, library maintenance attempts to use the LIBMAINTDIR disk

file. If the LIBMAINTDIR file is missing or if library maintenance encounters an error

while reading records from it, library maintenance reverts to using the directory on

the tape to determine what files are on the tape and where the files are on the tape.

Library maintenance may access the tape directory disk file for source tapes that library

maintenance originally generated with LIBMAINTDIR = TRUE, if the file is resident on the

disk family specified by the DL LIBMAINTDIR system command. If you specify TRUE for

a source tape that was originally generated with LIBMAINTDIR = TRUE, the tape

directory disk file for the tape must be resident on the disk family specified by the DL

LIBMAINTDIR system command, or library maintenance will wait with a “NO FILE”

RSVP.

Any attempt to purge a library maintenance tape for which there is a tape directory disk

file resident on the DL LIBMAINTDIR disk family requires approval by the operator.

Whenever a program or library maintenance overwrites a tape for which there is a

resident LIBMAINTDIR tape directory disk file the system removes that file from the

disk.

COPY or ADD Statement

6–86 8600 1047–506

LOCATECAPABLE

Indicates that the file requires a tape drive capable of processing the READ POSITION

and LOCATE BLOCK ID tape commands for fast tape access.

If the assigned tape drive is locate capable, then library maintenance automatically takes

advantage of this feature to do high-speed spacing in the following situations:

• COMPARE Option

Library maintenance uses the LOCATE BLOCK ID tape command to backspace to

compare the file. If you receive a RECOPY REQUIRED message and respond “OK,”

library maintenance uses LOCATE BLOCK ID to backspace to the beginning of that

file to recopy the file. If you respond with “OF,” the file is erased.

• LIBMAINTDIR for Destination Tapes

For a tape that is locate capable, library maintenance stores the BLOCK ID of the

start of each file it copies in the LIBMAINTDIR directory.

• LIBMAINTDIR for Source Tapes

If the original tape was created on a locate capable tape drive, and a LIBMAINTDIR

directory was created for the tape, then library maintenance uses the LOCATE

BLOCK ID information found in the LIBMAINTDIR directory to rapidly space up to

each of the files to be copied.

OFFSITE

When you specify OFFSITE for a tape destination, library maintenance updates the

onsite/offsite status of that tape in the volume library or in the volume directory.

If library maintenance does not successfully copy a file to a destination tape, it purges

the tape and does not update the onsite/offsite status for the tape.

If library maintenance successfully copies the files and OFFSITE is TRUE, then, when

library maintenance closes the tape, it updates the entry for the tape in the volume library

or in the volume directory to indicate that the volume or volumes are “offsite.” If library

maintenance successfully copies the files and OFFSITE is false, then, when library

maintenance closes the tape, it updates the entry for the tape in the volume library or in

the volume directory to indicate that the volume or volumes are “onsite.”

Note: Library maintenance performs these actions only when the tape volume is listed

in either the Volume Library, at sites that use the OP + CATALOGING option, or the

Volume Directory, at sites that use the SECOPT TAPECHECK = AUTOMATIC option.

SCRATCHPOOL

Indicates the scratch pool that the tape is retrieved from when files are copied. The

scratch pool name is a 17-character identifier. There is no default value.

COPY or ADD Statement

8600 1047–506 6–87

SERIALNO

Identifies the specific disk or tape volumes to be used when copying files. To copy a few

specific files from a multi-reel library maintenance tape set, you can use this attribute to

skip directly to the reel holding the file or files you need. If you know which reel contains

the file you want (or the first reel that contains one of the files you want), use the serial

number of that tape volume for the value of the SERIALNO attribute. The SERIALNO

attribute does not have a default value. For more information, refer to “Serial Number

Assignment” in Section 5.

UNITNO

Designates the assigned hardware unit number of the tape volume to be used when

copying files. In the case of a multi-volume tape set, UNITNO is applied only to the first

volume.

USERCODE

Passes log-on information, which consists of a usercode, password, and charge account,

to the remote host specified with the HOSTNAME attribute. The default value is a null

string (" "). The log-on information has a maximum length of 255 characters, which

include all quotation marks ("), single quotation marks or apostrophes ('), and slashes (/).

The USERCODE attribute is ignored if the HOSTNAME attribute is not specified, if Host

Services File Transfer is used, or if NFT is used.

YOURUSERCODE is an acceptable synonym for USERCODE.

WINDOWSIZE

Indicates the maximum amount of data, in octets, that can be outstanding between the

source and the destination processes involved in an NFT transfer. An octet is a unit of

data that is 8 bits in length.

Note: The WINDOWSIZE attribute is applicable only if an NFT transfer is executed. For

more information, refer to the Distributed Systems Services Operations Guide.

YOURNAME

Overrides the default value for the control port number. When you copy from a remote

system, specify YOURNAME in the <source volume> attributes. When you copy to a

remote system, specify YOURNAME in the <destination volume> attributes.

The following example copies a file to a remote system with an IP address of 1.1.1.1 and

assigns a port number of 123435:

COPY [FTP] A_FILE AS 'a.txt' TO DISK

(IPADDRESS = "1.1.1.1", YOURNAME = "12345")

Note: The control port number used by the Batch Client is determined in the following

order:

•

The default value: 21

•

The value from the Configuration File, if specified

•

The value of the YOURNAME volume attribute, if specified

COPY or ADD Statement

6–88 8600 1047–506

Examples

The following statements illustrate various aspects of the COPY statement with the

AUTOUNLOAD and SCRATCHPOOL file attributes.

The following statement will copy file X as A/B from disk PACK to tape T. Since the value

of AUTOUNLOAD file attribute is ON, the tape will be unloaded when the operation is

completed.

COPY X AS A/B FROM PACK TO T(KIND=TAPE, AUTOUNLOAD=ON);

The following statement will copy the file X as A/B from disk PACK to tape T in the TEST

scratch pool:

COPY X AS A/B FROM PACK TO T(KIND=TAPE, SCRATCHPOOL=TEST);

Additional File Attributes

You can specify the following additional file attributes for the destination volume attribute

list:

• CDCOPIES

• COMPRESSIONCONTROL

• COMPRESSIONREQUESTED

• DENSITY

• FAMILYINDEX

• LIBMAINTAPPEND

• LIBMAINTDIR

• LOCKEDFILE

• MULTIVOLUME

• PACKETWRITE

• SAVEFACTOR

• SECURITYGUARD

• SECURITYTYPE

• SECURITYUSE

• SENSITIVEDATA

• SINGLEUNIT

• USECATALOG

• VERSION

Notes:

• These file attributes cannot be specified for the source volume attribute list

construct.

• The tape attributes SECURITYGUARD, SECURITYTYPE, and SECURITYUSE only

work if the InfoGuard security enhancement software or the Security Accountability

Facility is installed and the TAPECHECK option of the SECOPT system command is

set to AUTOMATIC. If the TAPECHECK option of the SECOPT command is set to

NONE, these three attributes are ignored for disk and tape destination volumes.

COPY or ADD Statement

8600 1047–506 6–89

CDCOPIES

You can specify how many copies of a CD-R disc are to be burned with the attribute

CDCOPIES. The default value of CDCOPIES is 1.

When data is copied to a CD-R disk, it is first copied from the source media to a

temporary disk file. The data in the temporary disk file is formatted exactly as it is to

appear on the CD-ROM. The temporary disk file is then copied to a CD-R drive.

CDCOPIES causes the disk file to be copied to the CD-R drive as many times as you

specify, without having to recopy the data from the source media.

COMPRESSIONCONTROL

Determines whether data compression will occur for a specific tape volume. This

attribute must be selected before a tape volume is assigned.

When the value USER is selected, the value of the attribute

COMPRESSIONREQUESTED will determine whether compression will occur. When the

value SYSTEM is selected, compression will occur based upon the value of the

compression flag in the tape label.

For further information, refer to the File Attributes Reference Manual.

COMPRESSIONREQUESTED

This attribute only has significance for tape files if the COMPRESSIONCONTROL

attribute is set to a value of USER.

If COMPRESSIONCONTROL = USER, COMPRESSIONREQUESTED will determine

whether compression will occur for a tape file.

Compression will only occur if COMPRESSIONCONTROL = USER and

COMPRESSIONREQUESTED = TRUE.

For further information, refer to the File Attributes Programming Reference Manual.

DENSITY

Indicates the recording density of a magnetic tape volume. The default value for output

files is the density setting of the tape unit selected.

FAMILYINDEX

Designates a specific physical volume within a disk family. If you do not specify the

FAMILYINDEX attribute, the FAMILYINDEX value of each source file is used (if that file

has had explicit values specified for FAMILYINDEX). By specifying this attribute, you can

alter or erase the FAMILYINDEX attribute of the new copies. If you specify a value of 0

or an integer expression that equals 0 for the FAMILYINDEX attribute, the disk areas will

be allocated in the normal rotational order of the system.

COPY or ADD Statement

6–90 8600 1047–506