HP NonStop TACL Reference Manual
HP NonStop TACL Reference Manual
HP NonStop TACL Reference Manual
Reference Manual
Abstract
This publication describes the syntax and use of the HP Tandem Advanced Command
Language (TACL) variables, commands, and built-in functions.
Product Version
T9205D46, T9205H01
Supported Release Version Updates (RVUs)
This publication supports J06.03 and all subsequent J-series RVUs, H06.03 and all
subsequent H-series RVUs, G06.20 and all subsequent G-series RVUs, and D46.00
and all subsequent D-series RVUs, until otherwise indicated by its replacement
publications. Additionally, all considerations for H-series throughout this manual will
hold true for J-series also, unless mentioned otherwise.
Part Number
Published
429513-017
August 2013
Document History
Part Number
Product Version
Published
429513-013
T9205D46, T9205H01
November 2010
429513-014
T9205D46, T9205H01
August 2011
429513-015
T9205D46, T9205H01
February 2012
429513-016
T9205D46, T9205H01
August 2012
429513-017
T9205D46, T9205H01
August 2013
Legal Notices
Copyright 2013 Hewlett-Packard Development Company L.P.
Confidential computer software. Valid license from HP required for possession, use or copying.
Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software
Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under
vendor's standard commercial license.
The information contained herein is subject to change without notice. The only warranties for HP
products and services are set forth in the express warranty statements accompanying such products
and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be
liable for technical or editorial errors or omissions contained herein.
Export of the information contained in this publication may require authorization from the U.S.
Department of Commerce.
Microsoft, Windows, and Windows NT are U.S. registered trademarks of Microsoft Corporation.
Intel, Itanium, Pentium, and Celeron are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Java is a U.S. trademark of Oracle and/or its affiliates.
Motif, OSF/1, UNIX, X/Open, and the "X" device are registered trademarks and IT DialTone and The
Open Group are trademarks of The Open Group in the U.S. and other countries.
Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the
Open Software Foundation, Inc.
OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THE OSF MATERIAL PROVIDED
HEREIN, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
OSF shall not be liable for errors contained herein or for incidental consequential damages in
connection with the furnishing, performance, or use of this material.
1990, 1991, 1992, 1993 Open Software Foundation, Inc. This documentation and the software to
which it relates are derived in part from materials supplied by the following:
1987, 1988, 1989 Carnegie-Mellon University. 1989, 1990, 1991 Digital Equipment Corporation.
1985, 1988, 1989, 1990 Encore Computer Corporation. 1988 Free Software Foundation, Inc.
1987, 1988, 1989, 1990, 1991 Hewlett-Packard Company. 1985, 1987, 1988, 1989, 1990, 1991,
1992 International Business Machines Corporation. 1988, 1989 Massachusetts Institute of
Technology. 1988, 1989, 1990 Mentat Inc. 1988 Microsoft Corporation. 1987, 1988, 1989,
1990, 1991, 1992 SecureWare, Inc. 1990, 1991 Siemens Nixdorf Informationssysteme AG. 1986,
1989, 1996, 1997 Sun Microsystems, Inc. 1989, 1990, 1991 Transarc Corporation.
This software and documentation are based in part on the Fourth Berkeley Software Distribution
under license from The Regents of the University of California. OSF acknowledges the following
individuals and institutions for their role in its development: Kenneth C.R.C. Arnold,
Gregory S. Couch, Conrad C. Huang, Ed James, Symmetric Computer Systems, Robert Elz. 1980,
1981, 1982, 1983, 1985, 1986, 1987, 1988, 1989 Regents of the University of California.
Printed in the US
Glossary
Index
Figures
Tables
Legal Notices
Whats New in This Manual xvii
Manual Information xvii
New and Changed Information
About This Manual xix
Audience xix
Organization xix
Related Reading xx
Notation Conventions xxii
HP Encourages Your Comments
xvii
xxvi
1. Overview of TACL
Using TACL Interactively 1-1
Developing TACL Programs 1-2
Language Features 1-3
Program Development Tools 1-4
Using TACL With Other Subsystems 1-4
2. Lexical Elements
Character Set 2-1
Data 2-1
Variable Names 2-1
Upshifting 2-1
Special Characters 2-2
Metacharacters 2-2
Separator Characters 2-5
Question Mark (?) 2-6
Ampersand (&) 2-6
Template Characters 2-6
Operators 2-8
Constants 2-8
Hewlett-Packard Company429513-017
i
Inhalt
3. Expressions
3. Expressions
Operators 3-1
Arithmetic Operations 3-2
Logical Operations 3-2
4. Variables
An Overview of TACL Variables 4-1
Variable Names 4-2
Variable Levels 4-3
Declaring a Variable 4-3
Specifying a Level of a Variable 4-4
Deleting a Variable 4-5
Accessing Variable Contents 4-5
Using a Variable as an Argument 4-6
TEXT Variables 4-6
Sample Declarations 4-6
ALIAS Variables 4-6
Sample Declarations 4-7
Limitations 4-7
MACRO Variables 4-7
Macro Arguments 4-8
Sample Declarations 4-8
ROUTINE Variables 4-9
Routine Arguments 4-9
Sample Declaration 4-10
Comparing Argument Handling in Macros and Routines
STRUCT Variables 4-12
Elements of STRUCT Variables 4-12
Limitations on the Use of STRUCT Variables 4-12
Declaring a Structure Body 4-13
Declaring a Simple Data Item 4-15
Declaring an Array Data Item 4-18
Declaring a Substructure 4-19
Declaring FILLER Bytes 4-20
Redefining a Structure 4-23
4-11
Inhalt
5-11
6-9
Inhalt
8-12
Inhalt
Inhalt
Inhalt
8-262
9-16
Inhalt
Inhalt
Inhalt
Inhalt
Inhalt
9-359
Inhalt
A. Syntax Summary
A. Syntax Summary
:UTILS:TACL Commands and Functions
Built-In Functions and Variables A-7
STRUCT Declarations A-14
#SET Summary A-15
#DELTA Command Summary A-16
A-2
B. Error Messages
TACL Error Messages B-1
DEFINE Error Messages B-46
Process Creation Error Messages B-50
RCVDUMP Error Messages B-51
RCVDUMP Error Messages for H-Series Only B-51
RCVDUMP Error Messages for H-Series, G-Series and
D-Series B-54
RELOAD Error Messages B-58
RELOAD Error Messages for H-Series Only B-58
Omitslice Information and Error Messages B-61
HP NonStop TACL Reference Manual429513-017
xiii
Inhalt
B-62
RELOAD Error Messages for H-Series, G-Series and D-Series
EMS Messages B-69
Error Numbers B-70
B-62
6-9
Tables
Table 2-1.
Table 2-2.
Table 2-3.
Table 3-1.
Table 4-1.
Table 4-2.
Table 4-3.
Table 4-4.
Table 5-1.
Table 6-1.
Table 7-1.
Table 7-2.
Table 7-3.
Table 7-4.
Table 7-5.
Table 7-6.
Table 7-7.
Table 7-8.
Table 7-9.
Table 7-10.
Table 7-11.
Table 7-12.
Table 7-13.
Table 7-14.
Table 7-15.
4-3
Inhalt
Table 8-1.
Table 8-2.
Table 8-3.
Table 8-4.
Table 8-5.
Table 8-6.
Table 8-7.
Table 8-8.
Table 8-9.
Table 9-1.
Table 9-2.
Table 9-3.
Table 9-4.
Table 9-5.
Table 9-6.
Table 9-7.
Table 9-8.
Table 9-9.
Table 9-10.
Table 9-11.
Table 9-12.
Table 9-13.
Table 9-14.
Table 9-15.
Table 9-16.
Table A-1.
Table B-1.
Table B-2.
Table C-1.
9-356
Inhalt
Abstract
This publication describes the syntax and use of the HP Tandem Advanced Command
Language (TACL) variables, commands, and built-in functions.
Product Version
T9205D46, T9205H01
Supported Release Version Updates (RVUs)
This publication supports J06.03 and all subsequent J-series RVUs, H06.03 and all
subsequent H-series RVUs, G06.20 and all subsequent G-series RVUs, and D46.00
and all subsequent D-series RVUs, until otherwise indicated by its replacement
publications. Additionally, all considerations for H-series throughout this manual will
hold true for J-series also, unless mentioned otherwise.
Part Number
Published
429513-017
August 2013
Document History
Part Number
Product Version
Published
429513-013
T9205D46, T9205H01
November 2010
429513-014
T9205D46, T9205H01
August 2011
429513-015
T9205D46, T9205H01
February 2012
429513-016
T9205D46, T9205H01
August 2012
429513-017
T9205D46, T9205H01
August 2013
W h ats N e w in T h is M a n ua l
C ha n ge s to th e 42 95 1 3-01 6 m an u al
Added CLICVAL program and its function in Commands and Programs table.
Added IPUCOM program and its brief function in Commands and Programs table.
Added the detailed description of IPUCOM Program in chapter 8.
Updated Considerations section for FILEINFO Command on page 8-68.
Added reference to the Guardian Procedure Calls Reference manual for a list of
processor types and the associated number under Results on page 9-310.
Removed outdated table listing processors and their associated numbers from
9-310.
Reworded information under Result on page 9-309.
Updated error message for the FILEINFO command on page 8-68.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xviii
Audience
This manual is intended for all users of the TACL product, both users who intend to use
TACL primarily as a command interpreter, and those users who need to use the
extensible capabilities of TACL for programming. Also included in this manual are
descriptions of TACL operations that are restricted for use by system management
personnel only.
Organization
Section 1, Overview of TACL
Section 3, Expressions
Section 4, Variables
Section 7, Summary of
Commands and Built-In
Functions
Section 8, UTILS:TACL
Commands and Functions
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xix
A b ou t T h is M a nu a l
R ela te d R e ad in g
Related Reading
The following paragraphs list manuals that are related to the use of the TACL product,
either as a command interpreter or as a programming language.
Prerequisites
The Guardian Users Guide presents introductory material about the TACL product,
including:
To gain a basic understanding of the use of TACL, read the first four sections of the
Guardian Users Guide before using this manual. You should also be familiar with basic
programming concepts and terminology, such as pushing and popping (creating and
deleting) variables, using arguments, and so on.
Corequisites
If you use TACL as a programming language to create macros and routines, the TACL
Programming Guide presents task-oriented material and examples. (The TACL
Programming Guide does not, however, contain descriptions of restricted commands
and functions.) Additional sources of information depend on your use of the TACL
product. Manuals of possible interest include:
Manuals about utilities, such as the File Utility Program (FUP) Reference Manual.
Manuals about debugging programs in languages other than TACL (that you run
from TACL), such as the Debug Manual and the Inspect Manual.
Manuals about Distributed Systems Management (DSM), including:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xx
A b ou t T h is M a nu a l
C oreq u isite s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xxi
A b ou t T h is M a nu a l
N otation C on ve ntion s
Notation Conventions
Hypertext Links
Blue underline is used to indicate a hypertext link within text. By clicking a passage of
text with a blue underline, you are taken to the location described. For example:
This requirement is described under Backup DAM Volumes and Physical Disk
Drives on page 3-2.
A b ou t T h is M a nu a l
G e ne ra l S yntax N o ta tio n
{ } Braces. A group of items enclosed in braces is a list from which you are required to
choose one item. The items in the list can be arranged either vertically, with aligned
braces on each side of the list, or horizontally, enclosed in a pair of braces and
separated by vertical lines. For example:
LISTOPENS PROCESS { $appl-mgr-name }
{ $process-name }
ALLOWSU { ON | OFF }
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
INSPECT { OFF | ON | SAVEABEND }
Ellipsis. An ellipsis immediately following a pair of brackets or braces indicates that you
can repeat the enclosed sequence of syntax items any number of times. For example:
M address [ , new-value ]
[ - ] {0|1|2|3|4|5|6|7|8|9}
An ellipsis immediately following a single syntax item indicates that you can repeat that
syntax item any number of times. For example:
"s-char"
Punctuation. Parentheses, commas, semicolons, and other symbols not previously
described must be typed as shown. For example:
error := NEXTFILENAME ( file-name ) ;
LISTOPENS SU $process-name.#su-name
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must type as shown. For example:
"[" repetition-constant-list "]"
Item Spacing. Spaces shown between items are required unless one of the items is a
punctuation symbol such as a parenthesis or a comma. For example:
CALL STEPMOM ( process-id ) ;
If there is no space between two items, spaces are not permitted. In this example, no
spaces are permitted between the period and any other items:
$process-name.#su-name
Line Spacing. If the syntax of a command is too long to fit on a single line, each
continuation line is indented three spaces and is separated from the preceding line by
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xxiii
A b ou t T h is M a nu a l
a blank line. This spacing distinguishes items in a continuation line from items in a
vertical list of selections. For example:
ALTER [ / OUT file-spec / ] LINE
[ , attribute-spec ]
!i and !o. In procedure calls, the !i notation follows an input parameter (one that passes data
to the called procedure); the !o notation follows an output parameter (one that returns
data to the calling program). For example:
CALL CHECKRESIZESEGMENT ( segment-id
, error
) ;
!i
!o
!i,o. In procedure calls, the !i,o notation follows an input/output parameter (one that both
passes data to the called procedure and returns data to the calling program). For
example:
error := COMPRESSEDIT ( filenum ) ;
!i:i.
!i,o
In procedure calls, the !i:i notation follows an input string parameter that has a
corresponding parameter specifying the length of the string in bytes. For example:
error := FILENAME_COMPARE_ ( filename1:length
, filename2:length ) ;
!i:i
!i:i
!o:i. In procedure calls, the !o:i notation follows an output buffer parameter that has a
corresponding input parameter specifying the maximum length of the output buffer in
bytes. For example:
error := FILE_GETINFO_ (
filenum
, [ filename:maxlen ] ) ;
!i
!o:i
123.00
The user must press the Return key after typing the input.
Nonitalic text. Nonitalic letters, numbers, and punctuation indicate text that is displayed or
returned exactly as shown. For example:
Backup Up.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xxiv
A b ou t T h is M a nu a l
lowercase italic letters. Lowercase italic letters indicate variable items whose values are
displayed or returned. For example:
p-register
process-name
[ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For
example:
Event number = number [ Subject = first-subject-value ]
A group of items enclosed in brackets is a list of all possible items that can be
displayed, of which one or none might actually be displayed. The items in the list can
be arranged either vertically, with aligned brackets on each side of the list, or
horizontally, enclosed in a pair of brackets and separated by vertical lines. For
example:
proc-name trapped [ in SQL | in SQL file system ]
{ } Braces. A group of items enclosed in braces is a list of all possible items that can be
displayed, of which one is actually displayed. The items in the list can be arranged
either vertically, with aligned braces on each side of the list, or horizontally, enclosed in
a pair of braces and separated by vertical lines. For example:
obj-type obj-name state changed to state, caused by
{ Object | Operator | Service }
process-name State changed from old-objstate to objstate
{ Operator Request. }
{ Unknown.
}
| Vertical Line. A vertical line separates alternatives in a horizontal list that is enclosed in
brackets or braces. For example:
Transfer status: { OK | Failed }
% Percent Sign. A percent sign precedes a number that is not in decimal notation. The
% notation precedes an octal number. The %B notation precedes a binary number.
The %H notation precedes a hexadecimal number. For example:
%005400
%B101111
%H2F
P=%p-register E=%e-register
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xxv
A b ou t T h is M a nu a l
C ha n ge B a r N o ta tio n
UPPERCASE LETTERS. Uppercase letters indicate names from definition files. Type these
names exactly as shown. For example:
ZCOM-TKN-SUBJ-SERV
lowercase letters. Words in lowercase letters are words that are part of the notation,
including Data Definition Language (DDL) keywords. For example:
token-type
!r.
The !r notation following a token or field name indicates that the token or field is
required. For example:
ZCOM-TKN-OBJNAME
!o.
token-type ZSPI-TYP-STRING.
!r
The !o notation following a token or field name indicates that the token or field is
optional. For example:
ZSPI-TKN-MANAGER
token-type ZSPI-TYP-FNAME32.
!o
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
xxvi
Overview of TACL
As a programming language, the TACL product is most often used for managing
systems and processes. You can, for example, use TACL to:
The TACL language consists of commands, built-in functions, and built-in variables.
Commands are typically used for interactive work. Built-in functions are typically used
for programmatic work. Built-in variables store environmental information; you can set
and retrieve their values.
Procedural constructs such as flow control statements are provided as part of the set of
built-in functions. In addition, TACL provides powerful text manipulation functions that
process output and results from processes.
TACL is extensible. Consult the documentation that accompanies each software RVU
to determine if additional function has been added.
Runs a process
STATUS
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
1-1
O vervie w o f T A C L
Your environment can include user-defined commands if you or your system manager
define them.
To start a process (such as FUP) or use a TACL command (such as TIME), type the
program name; this is known as invoking the program or the command. If you type a
command incorrectly, TACL issues an error message and includes the expected
syntax. You can then retype the command.
To obtain syntax help while you are typing a command, press the F16 key (or the
appropriate help key defined in your environment) at the point in the command where
you want help.
The Guardian Users Guide provides detailed instructions for using TACL interactively,
including:
The use of commands is the simplest interactive use of TACL. You can, however,
access TACL built-in variables and functions or run your own procedural constructs
interactively, as follows:
Display the contents of TACL built-in variables by typing the variable name
(including the initial number sign).
Invoke a TACL built-in function by typing the function name enclosed in square
brackets.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
1-2
O vervie w o f T A C L
La ng u ag e F ea tu re s
TACL allows you to interact with processes, handle results, and make decisions about
further actions; it provides string-handling capabilities, character-handling capabilities,
exception-handling capabilities, and many built-in functions that provide information
about the system environment. You can use TACL to interface with the Subsystem
Programmatic Interface (SPI), the Event Management Service (EMS), and other
utilities and programs.
This manual describes TACL syntax and semantics. For more information about how to
use TACL for specific programming tasks, see the TACL Programming Guide.
Language Features
TACL provides a set of predefined commands, functions, and data variables. These
entities are built into the TACL language and are the building blocks with which you
construct TACL programs:
TACL built-in functions are intended for use in TACL programs. Built-in function
names start with a number sign (#). Most functions return a result that can be
analyzed programmatically. Examples include:
#ARGUMENT
#INPUT
#PROCESSINFO
Built-in functions also provide flow control, such as loop control and exit
mechanisms. To see a list of functions, use the #BUILTINS built-in function or see
Section 9, Built-In Functions and Variables.
TACL built-in variables contain information about the TACL environment. Built-in
variable names start with a number sign (#). These variables are used primarily to
establish the TACL environment. You can set and retrieve their values, and create
new instances of these variables, but you cannot delete the variables themselves.
Examples of these variables include:
#OUT
#PMSG
#MYTERM
TACL commands (such as RUN and STOP) are intended for interactive use, but
you can use them in TACL programs. Commands do not return status or error
information; they usually display results.
TACL provides these procedural features:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
1-3
O vervie w o f T A C L
P rog ra m D e ve lo pm e nt T oo ls
Data types. TACL interprets text variables as text unless you request an
arithmetic or logical operation. TACL supports an extensive set of data types
for STRUCT variables and for arguments to routine variables. Programs. TACL
programs allow you to define a block of TACL statements that performs one or
more tasks. You can access a TACL program from other TACL programs; you
can nest programs within other programs. For a description of TACL programs,
see Section 5, Statements and Programs.
Argument passing. You can pass arguments to TACL programs. The
mechanism depends on the type of program (text, macro, or routine).
Data operations. You can compare, move, and manipulate the contents of
variables that contain text or TACL statements.
For additional information about TACL programs, see Section 5, Statements and
Programs.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
1-4
Lexical Elements
Character Set
Special Characters
Constants
Reserved Words
Comments
Character Set
TACL supports the ISO 8859.1 (International Organization for Standardization)
character set, also called the ECMA-94 (European Computer Manufacturers
Association) character set, which is an 8-bit character set with 256 character positions.
The first 128 characters are the same as the ASCII (American Standard Code for
Information Interchange) character set; ISO 8859.1 is a superset of ASCII.
The high-order 128 positions include 94 characters that are used in the majority of
western European languages, plus two additional formatting characters: a nonbreaking
space and an optional or discretionary hyphen.
Data
You can use all characters in the ISO character set as data.
Variable Names
You can use all printable characters in TACL variable names; however, you can use
only the low-order (ASCII) characters in the names of systems, disk volumes,
subvolumes, files, processes, and devices.
Upshifting
TACL automatically upshifts variable names when it defines them. If a variable name
contains lowercase letters that contain diacritical marks (marks added to a letter to
indicate a special phonetic value), those characters may lose their diacritical marks
when upshifted using CPRULES0. This upshifting can change the apparent identity of
the variable. To avoid errors, use uppercase letters if your variable name includes
diacritical marks.
TACL provides two files that contain coded rules for upshifting characters:
CPRULES0 contains the rules used by the majority of western European countries;
this is the default set of character-processing rules.
CPRULES1 contains the rules used primarily by Spain and French Canada.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-1
S p ecial C ha racters
Special Characters
There are six types of characters that have special meaning to TACL:
Character Name
Description
Metacharacters
Separator
Question mark
Ampersand
Template
Operator
Metacharacters
The interpretation of special characters as metacharacters depends on the setting of
the #INFORMAT Built-In Variable on page 9-196. The display of special characters
depends on the setting of the #OUTFORMAT Built-In Variable on page 9-274.
The #INFORMAT built-in variable affects the interpretation of special characters read
from the IN file, including terminal input and files read by the OBEY command.
#INFORMAT can have one of three values:
?TACL MACRO files, ?TACL ROUTINE files, and library files read by LOAD or #LOAD
are read in TACL format unless they contain ?FORMAT directives that specify PLAIN
or QUOTED format. For more information about the ?FORMAT directive, see
Section 5, Statements and Programs.
Note. TACL treats metacharacters as PLAIN when they are transmitted by #REQUESTER or
#SERVER, so characters obtained from these functions do not retain their special properties.
For example, square brackets in text obtained from a file opened by #REQUESTER do not
cause enclosed text to be expanded. This also applies to FILETOVAR and VARTOFILE, which
use the #REQUESTER built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-2
M e ta cha racters
Name
Description
[]
Square
brackets
Double
equal signs
==
Pairs of
braces
||
Pair of
vertical
lines
Tilde
Square Brackets ([ ])
You can use square brackets in several ways:
To extend a logical line past the physical line limit. If you enclose more than one
line within a pair of square brackets, the brackets mark the beginning and ending of
the logical line. You can extend the line to a maximum of 239 characters.
To define an enclosure that contains a label and one or more TACL statements.
Enclosures can be used in #CASE, #DEF, #IF, and #LOOP built-in functions. For
more information about enclosures and labels, see Function Calls on page 5-1.
To specify that TACL expand a variable name to the contents of the variable. When
TACL expands a variable name, it replaces the variable name with the contents of
the variable. To expand the variable, enclose the name of the variable in square
brackets. For information about variables, see Section 4, Variables.
If the variable contains text, TACL replaces the bracketed variable name with the
text stored in the variable. For example, if the variable var1 contains the integer 3,
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-3
M e ta cha racters
you can enclose var1 in square brackets to obtain the contents of var1 or you can
omit the brackets to obtain the text var1:
12> #OUTPUT [var1]
3
13> #OUTPUT var1
var1
14>
If the variable is a routine that contains executable TACL statements, TACL
interprets the executable statements and replaces the variable name with the result
of the statements.
When specifying the contents of a variable as an argument to a command or built-in
function, you do not always need to enclose the variable name in square brackets:
TACL evaluates the contents of square brackets before other portions of a statement.
This example illustrates the effect of square brackets on invocation sequence.
#OUTPUT is a built-in function that sends its argument to the TACL OUT file.
18> #OUTPUT #PMSEARCHLIST
#PMSEARCHLIST
19> #OUTPUT [#PMSEARCHLIST]
#DEFAULTS $HOME.SUBV $SYSTEM.SYSTEM
20> [#OUTPUT] #PMSEARCHLIST
#PMSEARCHLIST expanded to:
#DEFAULTS $HOME.SUBV $SYSTEM.SYSTEM
In the first case, line 18, TACL expands the #OUTPUT function first because it
encounters it first; there are no square brackets in the command line. The #OUTPUT
function uses the simple text #PMSEARCHLIST as its argument.
In the second case, line 19, TACL expands #PMSEARCHLIST first because of the
brackets. The #PMSEARCHLIST built-in variable returns the list of subvolumes in the
program and macro search list; TACL then expands #OUTPUT with that text as its
argument.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-4
S ep a ra to r C ha racters
In the third case, line 20, TACL expands #OUTPUT entirely within the limits of the
square brackets, producing a blank line of output; then TACL invokes
#PMSEARCHLIST.
If you need to output a square bracket from a TACL program, you can use the ~[
combination described in Table 2-1 on page 2-3.
Tilde (~)
The tilde is used in combination with another character:
Separator Characters
Most data supplied to TACL must end with a separator character. For example,
keywords, file names, and variable names must end with a standard TACL separator;
numbers and tokens, on the other hand, need not end with a separator character.
Note. You cannot use these characters in the KEYWORD and TOKEN definitions of the
#ARGUMENT built-in function.
Name
Space
Comma
Left parenthesis
Right parenthesis
Slash
Semicolon
carriage return
~;
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-5
Q ue stion M ark (? )
To start a line with a question mark for any other purpose, use two question marks.
TACL then discards the first question mark and any adjacent spaces and treats the
remainder of the line as text.
Ampersand (&)
An ampersand (&) at the end of a line of TACL commands or function calls signals that
the line continues on the next physical line. This continuation applies to executable
statements and comments, with two exceptions:
TACL does not interpret data transmitted by a process or file opened using
#REQUESTER or #SERVER; any special characters are treated as text. If you
receive a line that contains an ampersand, TACL does not view the ampersand as
a continuation character.
You cannot use the continuation character with a TACL directive (a line beginning
with a question mark).
Note. TACL strips off comments when converting text from external format to internal format,
so any ampersand that appears before a comment appears to be at the end of the line. This
behavior can cause TACL to treat the next line as a continuation of the previous line.
The maximum line length is 239 characters; if a line is longer than 239 characters, TACL
truncates the line to 239 characters.
Template Characters
Templates are special constructs that allow you to perform simple pattern-matching
operations. For example, the command
FILENAMES c?t
displays all three-letter file names in the default volume and subvolume that begin with
C and end with T, such as CAT or CUT. The command
FILENAMES cat*
displays all file names that begin with CAT, regardless of name length, such as CAT,
CATALOG, or CATERERS. You can use templates to specify several entities with
similar names in a single request. TACL supports templates for file names and
DEFINEs.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-6
T em p late C ha racters
Subvolume Templates
Several TACL commands and built-in functions allow you to supply subvolume
templates in place of actual subvolume names. The TACL command or built-in function
then operates on one or more similarly named files. A subvolume specification includes
these fields:
[[[\node-name.]$volume-name.] subvolume-name.]
A subvolume template follows the format of a file name, but contains one or more of
the template characters listed in Table 2-3, in place of specific characters in the file
name. You can include these template characters in any field of the subvolume
specification except the node-name field, which does not allow the * character. In
addition, template characters cannot match a volume identifier ($) or a field separator
(.) in a file name.
File-Name Templates
Several TACL commands and built-in functions allow you to supply file-name templates
in place of actual file names. The TACL command or built-in function then operates on
one or more similarly named files. A file-name specification includes these fields:
[[[\node-name.]$volume-name.] subvolume-name.] file-name
A file-name template follows the format of a file name, but contains one or more of the
template characters listed in Table 2-3, in place of specific characters in the file name.
You can include these template characters in any field of the file-name specification
except the node-name field, which does not allow the * character. In addition, template
characters cannot match a volume identifier ($) or a field separator (.) in a file name.
Table 2-3. Template Characters
Character
Description
DEFINE Templates
Most TACL functions that allow DEFINEs allow you to specify templates for DEFINE
names. These templates use the same characters as file-name templates, with the
added convention that you can use these patterns to refer to all existing DEFINEs:
=* or **
For more information about DEFINEs, see Section 5, Statements and Programs and
the Guardian Users Guide.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-7
O p erators
Operators
Operators perform mathematical or logical operations on values. The operators
provided by TACL can be divided into three categories:
Arithmetic
Logical
String
Constants
A constant is a value that you can store in a variable, use as a literal, or specify as part
of an expression. There are two types of TACL constants: text constants and string
constants. An integer is a special type of text constant.
Text Constants
A text constant is any sequence of these characters:
TACL ignores leading and trailing spaces when interpreting a text constant.
Use a text constant with functions that accept text arguments. For example, the
#REPLY built-in function accepts a text argument. Built-in functions that accept text
arguments use all the remaining text on the line, with leading and trailing spaces and
end-of-line characters removed.
These text constants are valid:
DATA1
456
Please type a number
An integer is a special type of text constant that consists of a sequence of digits. The
sequence can include a prefix that specifies a positive or negative sign. Many integers
in this manual are listed with commas for clarification. Do not, however, include
commas when you specify an integer. TACL does not accept commas in integers.
Integer-constant:
[ + | - ]{ 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }...
An integer constant can be written as one or more decimal digits (0-9) with an optional
sign prefix (+ or -). A TACL integer is similar to the FIXED numeric constant available in
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-8
S tring C o n sta n ts
145
4
-89776
TACL uses integer values for logical operations and comparisons. TACL interprets zero
as FALSE and nonzero integers as TRUE.
String Constants
A string constant is any sequence of these characters, enclosed within a pair of
quotation marks ( ):
You can include leading and trailing spaces within the quotation marks. Use a string
constant with functions that accept string arguments. In addition, you can use a string
constant in place of a variable level in many built-in functions, such as built-in functions
that manipulate variables (functions with names that end in V). For example, the
#LINEFINDV function accepts a string constant.
These string constants are valid:
Error on input
456
Reserved Words
A reserved word is a predefined, symbolic name that has special meaning to TACL.
Reserved words cannot be redefined; if you try to redefine one, TACL returns an error.
Reserved words include:
To define a new level of a built-in variable, use the PUSH command or the #PUSH
built-in function. You can then specify a new value for the built-in variable while
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-9
C o m m e n ts
preserving the former value. For more information about variables and variable levels,
see Section 4, Variables.
Note. TACL does not prevent you from redefining TACL commands. You can, for example,
define a macro or function with the name TIME-a standard TACL command. You can also load
a segment file that has the same name as a TACL command. If you make such a change,
TACL will not act in its standard manner; it will, instead, execute your code.
Comments
TACL supports three forms of comments:
C o m m e n ts
If the text contains braces, the rules for that form of comment also apply.
Comment text is terminated by the end of the command line unless you continue
the line with the line continuation character (&):
COMMENT This is == a valid }{ comment
COMMENT This is also a valid comment &
that is carried over to the next line
COMMENT {This {thing} is an invalid comment}
In all forms of comments, comment text is optional. TACL does not support nested
comments.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-11
C o m m e n ts
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
2-12
Expressions
Operators
Operators perform operations on values. The operators provided by TACL can be
divided into four categories:
Arithmetic
Relational
Logical
String
Operators have an order of precedence; when several operations take place within the
same program statement, operations with higher precedence are performed before
operators with lower precedence. Table 3-1 lists the category, function, and relative
precedence of each operator; a lower number indicates higher precedence. To change
the order of precedence, use parentheses. A subexpression in parentheses is
evaluated before the rest of the expression that contains it.
Table 3-1. TACL Operators (page 1 of 2)
Operator
Function
Type of Operation
Precedence
NOT
NOT
Logical
Multiplication
Arithmetic
Division
Arithmetic
Addition
Arithmetic
Subtraction
Arithmetic
>
Greater than
Relational (integers)
<
Less than
Relational (integers)
>=
Relational (integers)
<=
Relational (integers)
Equal to
Relational (integers)
<>
Not equal to
Relational (integers)
Concatenation
String
'>' or '!>'
Greater than
Relational (strings)
'<' or '!<'
Less than
Relational (strings)
'>=' or '!>='
Relational (strings)
'<=' or '!<='
Relational (strings)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
3-1
E xp re ssio n s
Function
Type of Operation
Precedence
'=' or '!'
Equal to
Relational (strings)
'<>' or '!<>'
Relational (strings)
AND
AND
Logical
OR
OR
Logical
String operators that include an exclamation point (!) are case-sensitive; those without
exclamation points make no distinction between uppercase and lowercase letters.
The apostrophes around each string operator are part of each operator and must be
present.
Arithmetic Operations
TACL supports arithmetic operations on integers. As with integer-based arithmetic in
other languages, perform multiplication operations before division operations to obtain
the greatest precision.
Logical Operations
TACL supports logical operations and comparisons for integer and string operands.
TACL interprets 0 as FALSE and nonzero integers as TRUE, and typically returns -1 or
1 as the nonzero (TRUE) result for built-in function results. String comparison
operators are enclosed in single quotes to differentiate them from numeric operators.
For example, assuming STATE is a variable containing text and COUNT is a variable
containing a number, this #IF condition could be stated:
[#IF STATE '=' "DONE" OR COUNT = 10 |THEN| ...
String comparison and numeric comparison yield different results. If, for example, one
variable contains 10 and the other contains 010, the two values are equal numerically
but unequal in the string sense (they are = but are not '=').
To perform operations interactively, use the COMPUTE command. To obtain the value
of an expression for use by other code, use the #COMPUTE built-in function. Note,
however, that if a function accepts an expression as an argument, you do not need to
specify #COMPUTE. For example, this statement evaluates the embedded arithmetic
expression because the #IF function accepts an expression as an argument:
[#IF A+1 = 3 |THEN|
...
]
To obtain the value of an expression, use the COMPUTE command (interactive) or the
#COMPUTE built-in function (programmatic).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
3-2
E xp re ssio n s
L o gica l O p eration s
If you use a variable as an operand, you do not need to enclose the variable name in
square brackets.
Note. TACL evaluates all operands in a logical expression, even after the first FALSE (in an
AND expression) or the first TRUE (in an OR expression). Therefore, all variables used in such
expressions must first be initialized using #SET or a similar command or built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
3-3
E xp re ssio n s
L o gica l O p eration s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
3-4
Variables
In many other languages, the term variable refers to a simple variable that contains a
single element, such as the number 10, or a more complex variable that contains an
set of elements. In TACL, a variable can contain a single element, a set of elements, or
information as diverse as a hierarchy of variables or a series of TACL statements.
You can create, set, and delete variables. You can access variables interactively or
load them into memory from a file. For more information about loading variables, see
Section 5, Statements and Programs.
This subsection provides general information about variables, including a discussion of
the stack organization of variables. The remainder of this section provides information
about each type of TACL variable.
Along with the variables you create, TACL supplies a set of variables. These variables
are called built-in variables and are listed in Section 9, Built-In Functions and Variables.
Description
TEXT
ALIAS
MACRO
ROUTINE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-1
V a ria ble s
V a ria b le N am e s
Description
STRUCT
Contains binary data and a set of type definitions that control the
conversion of the binary information to and from associated textual
representations
DELTA
DIRECTORY
Variable Names
A variable name can contain from 1 to 31 characters and must start with a letter. The
name can contain letters, numbers, underscore characters (_), and circumflexes (^).
Variable names are not case-sensitive. These are valid variable names:
var1
ems^text^info
write_data
Never create variables whose names begin with a circumflex (^) and never use, in
any way, such variables supplied as part of a TACL software RVU.
Do not create or use variables whose names begin with an underscore (_), except
where specifically permitted as a feature of a TACL software RVU.
Do not create any variables under :UTILS. Similarly, the associated source file,
TACLSEGF, can contain only TACL programs supplied as part of a TACL software
RVU.
Do not create any variables under :UTILS_GLOBALS except where specifically
permitted.
Do not push or pop :UTILS or :UTILS_GLOBALS.
If you modify the use list, ensure that your use list always includes certain
directories necessary for the correct operation of TACL programs supplied as part
of a TACL software RVU. The USE command automatically does this for you. The
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-2
V a ria ble s
V a riab le Le ve ls
list of necessary directories depends on the TACL software RVU and must not be
hard coded in your TACL programs.
Variable Levels
A variable level is an important organizational concept associated with TACL variables.
Whenever you create a variable, TACL creates a stack for the variable. Each element
of the stack is known as a variable level. The stack organization allows you to create
local copies of a variable. You can delete the local copies when you exit the local
environment, restoring the variable to its original value.
When you add a new variable level, TACL pushes the stack down by one level; when
you remove a level, TACL pops the stack by one level.
Note. Descriptions in this manual sometimes use the term variable to mean variable level,
for brevity.
This diagram illustrates a sample variable, var1, that contains three levels:
Variable Name and Level
var1.3 (top), also accessible as var1
Contents
XYZ
var1.2
var1.1
35
Declaring a Variable
Table 4-2 lists TACL functions that allocate and define variables.
Table 4-2. Functions and Commands That Allocate and Define Variables
Command
(Interactive)
Function
(Programmatic)
PUSH
#PUSH
#DEF
SET
VARIABLE
#SET, #SETV,
#SETMANY
Description
In addition, the ?SECTION directive allows you to declare any type of TACL variable.
To access such variables, you must LOAD the file that contains them.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-3
V a ria ble s
S p ecifyin g a L e ve l o f a V a ria b le
The choice of a declaration mechanism depends on whether you want to define the
variable interactively, within a file, or in a library. For more information about files and
libraries, see Section 5, Statements and Programs.
When you create a variable, TACL creates level 1 of the variable. To create additional
levels, push or define the same variable. TACL then creates a new level of the variable
and increments the level number.
You can use the #FRAME built-in function at the start of a macro or routine to define a
local environment for variables. If you create variables within a frame, you can remove
all the variables and their levels by deleting the frame with an #UNFRAME or #RESET
FRAMES operation.
A variable remains in existence unless you delete it with a #POP function call, POP
command, an #UNFRAME operation, or a #RESET FRAMES operation.
Numbers greater than zero refer to levels relative to the bottom of the stack; they
indicate the order of creation of the levels. As an example, name.1 is the bottom
level, name.2 is the next to the bottom level, and so on.
Numbers less than or equal to zero refer to levels relative to the top of the stack;
they indicate how far down a level is from the top of the stack. Therefore, name.0
is the top level, name.-1 is the next to the top level, and so on.
This diagram shows the two ways to address levels of the sample variable var1:
Bottom-Up Addressing
var1.3 (top), also accessible as var1
Top-Down Addressing
XYZ
var1.0
var1.2
var1.-1
var1.1
35
var1.-2
Different levels can contain different types of data. For example, the first level of a
variable could contain an alias, the second level could contain text, and the third level
could contain a macro.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-4
V a ria ble s
D e leting a V a ria b le
Deleting a Variable
Table 4-3 lists TACL functions that delete variables.
Table 4-3. Functions and Commands That Delete Variables
Command
(Interactive)
Function
(Programmatic)
Description
POP
#POP
KEEP
#KEEP
#UNFRAME
#RESET
FRAMES
To access the contents of a variable from a location that expects text, enclose the
variable name in square brackets ([]). When TACL encounters a variable name in
square brackets, it replaces the variable name with the contents of the variable;
this action is known as expanding a variable. For example:
#OUTPUT [var1]
If the variable is a routine that contains TACL statements, TACL replaces the
variable name with its associated statements, interprets the statements, and
produces results as directed by the statements. The result ends up in place of the
variable name, making the result very accessible to your program.
If you include a level number within the square brackets, TACL expands the
contents of the variable level. If you omit the level number, TACL expands the top
level of the variable.
If you are calling a variable as a simple function, then you do not need to surround
the function call with brackets. This example shows a #SET function call without
square brackets surrounding it:
#SET temp 123
V a ria ble s
|ELSE|
#OUTPUT Value is OK
]
TEXT Variables
A text variable can contain:
Sample Declarations
This TACL statement creates a TEXT variable called x:
#PUSH x
This TACL statement creates a TEXT variable called var1 and assigns the value 3 to
var1:
[#DEF var1 TEXT |BODY| 3]
This example creates a TEXT variable called printit; this variable contains TACL
statements:
?SECTION printit TEXT
#OUTPUT Here is line one
#OUTPUT Here is line two
#OUTPUT I'm finished!
To use this code, you must first load the file that contains the code. For more
information, see Section 6, The TACL Environment.
ALIAS Variables
An alias is a limited variable; its contents must be exactly one word-the name of a
variable or a file. (Comments of the == and { } forms are allowed, because TACL
deletes them; but COMMENT lines are not allowed, because they remain.) An alias is
simply a name for something else; for example, the variable S could be an alias for
STATUS.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-6
V a ria ble s
S am p le D eclaration s
For example, if you replace the TACL STATUS command with a macro called STATUS,
you can no longer use the TACL STATUS command. To access the TACL STATUS
command, you must make the variable S an alias for :UTILS:TACL:STATUS.
You can also use alias variables to define function keys. For more information, see the
Guardian Users Guide.
Sample Declarations
This definition defines the variable S as an alias for the STATUS command:
[#DEF s ALIAS |BODY| STATUS]
After loading this definition, type the letter s to obtain status information.
Limitations
An alias must define something TACL can actually execute. TACL generates an error if
an alias returns simple text. A macro (described in MACRO Variables) does not have
this restriction. For example, given these definitions:
34> [#DEF a ALIAS |BODY| Huzzah]
35> [#DEF m MACRO |BODY| Huzzah]
you could do this:
36> #OUTPUT [m]
Huzzah
but not this:
37> #OUTPUT [a]
Huzzah
^
Expecting ...
followed by lists of what the alias could have been, followed by
#OUTPUT [a]
^
*ERROR* Cannot resolve alias
38>
MACRO Variables
A macro variable contains TACL statements; a macro can include conditional logic and
can invoke other macros and functions. When TACL encounters a macro name, it
replaces that name with the entire contents of the macro and interprets it, performing
the specified work.
If you declare variables within the macro and use #FRAME and #UNFRAME to
precede and follow their declaration and use, TACL deletes the variables before you
exit the macro.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-7
V a ria ble s
M a cro A rg u m e n ts
For information about TACL statements, see Section 5, Statements and Programs. For
additional examples of TACL macros, see the TACL Programming Guide.
Macro Arguments
A macro accesses arguments by position. To access an argument, specify the position,
enclosed in percent signs (% n%). For example, %1% references the first argument
supplied when the variable is invoked. Table 4-4 lists several ways to access macro
arguments from within a macro.
Table 4-4. Macro Arguments
Argument Form
Description
%0%
%n%
%n1 TO n2%
%n1 to *%
%n1 TO n2 BY n3%
%n1 TO * BY n3%
%*%
All arguments
When you invoke a macro, you supply arguments as a space-separated list. TACL
substitutes the real arguments in place of the dummy arguments. If you supply more
arguments than are used in the macro, TACL ignores the extra arguments.
Because of the use of the percent sign to denote dummy arguments, if you want to
include a literal percent sign in a macro, enter it twice (%%).
Sample Declarations
This code defines a macro called fn that calls FILENAMES with the first argument
supplied to fn:
?SECTION fn MACRO
FILENAMES %1%
If the argument is not a file-name template, TACL returns an error. You could also use
#DEF to define this macro:
[#DEF fn MACRO |BODY| FILENAMES %1%]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-8
V a ria ble s
R O U T IN E V a ria ble s
ROUTINE Variables
A routine variable contains TACL statements. When TACL encounters a routine, it
executes the routine and replaces the invocation with the results returned by the
routine.
TACL routines support these capabilities that are not provided by text variables or
macro variables:
TACL executes a routine within a separate buffer; the only result is generated by one
or more #RESULT built-in functions within the routine. The important distinction
between macros and routines is that a macro invocation returns the entire text of the
macro to be executed; a routine invocation returns only what the #RESULT function
provides.
You can perform exception handling in routines to retain control in case of error
instead of giving up control to the TACL automatic exception-handling logic. For more
information, see the TACL Programming Guide.
For more information about TACL statements, see Section 5, Statements and
Programs. For additional examples of routines, see the TACL Programming Guide.
Routine Arguments
A routine does not use dummy arguments (% n%) for its method of argument handling.
Instead, use the #ARGUMENT built-in function within the routine to examine and
validate arguments and assign their values to variables for use within the function.
#ARGUMENT checks arguments one at a time to see if they satisfy any one of a list of
argument types. For some types of arguments, such as disk files, ensure that the
argument refers to an existing object or that the argument represents a syntactically
correct name for an object. (For example, the file associated with a file name must
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-9
V a ria ble s
S am p le D e clara tio n
exist to be a valid file-name argument, but if you specify SYNTAX, TACL checks only
for correctness of the file-name syntax.)
If the argument matches a listed type, the argument is placed into a specified variable,
and TACL returns a number that indicates the argument type. If the argument does not
fit any of the specified types, the routine terminates and generates an error message,
listing the types of arguments that were expected.
To parse arguments to a routine, use the #ARGUMENT built-in function. The
#ARGUMENT function allows you to define the types of arguments that can be
processed by the routine. TACL searches this list from left to right when it processes
each argument and returns the position (in the list) of the first argument type that
matches the argument.
If you declare variables within the routine, surround their declaration and use with
#FRAME and #UNFRAME calls, TACL deletes the variables before you exit the
routine.
Sample Declaration
This code defines a routine variable called day_of_the_week that contains a series of
TACL statements. The routine accepts a timestamp as its argument; the argument is
optional:
?SECTION day_of_the_week ROUTINE
#FRAME
#PUSH days timestamp rslt
== Accept one argument that is a timestamp.
#SET rslt [#ARGUMENT /VALUE timestamp/ NUMBER END]
[#CASE [rslt]
|1| SINK [#ARGUMENT END] == A valid timestamp was supplied
|2| == No timestamp; use the current timestamp:
#SET timestamp [#TIMESTAMP]
|OTHERWISE|
== Unexpected value from #ARGUMENT
#OUTPUT Invalid argument
#UNFRAME
#RETURN
]
== Calculate the numbers of days since 0 and since
== the beginning of the week
#SET days [#COMPUTE [timestamp]/(24*60*60*100) ]
== Return the day of the week.
#SET days [#COMPUTE days - ((days/7) * 7)]
#RESULT [#CASE [days]
|0| Tuesday
|1| Wednesday
|2| Thursday
|3| Friday
|4| Saturday
|5| Sunday
|6| Monday
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-10
V a ria ble s
]
#UNFRAME
The SINK commands discard the results of #ARGUMENT and prevent TACL from
echoing to the TACL OUT file. A successful evaluation returns 1; otherwise, the routine
terminates with an error. You could also use a #SET call to evaluate the results.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-11
V a ria ble s
S T R U C T V a ria ble s
The VALUE option of the #ARGUMENT function returns the fully qualified form of the
file-name argument.
STRUCT Variables
A STRUCT variable, or structure, is a special-purpose variable that contains a set of
named and typed data items that you can access individually or as a group. Use
STRUCTs to access the Subsystem Programmatic Interface (SPI), the Event
Management Service (EMS), or if you need to store binary data such as 6530 terminal
escape sequences.
TACL STRUCT variables support a wide range of data types. STRUCT variables can
contain simple data items, arrays, and other structures (called substructures).
Structures usually contain related data items. For example, a structure might contain a
process name, the primary CPU,PIN of the process, and its backup CPU,PIN.
A name
A body that can contain:
To declare a STRUCT, use #DEF or ?SECTION to declare a structure body and all
items and substructures associated with the body. For each STRUCT, TACL stores two
types of information: access information and the actual data. (If you declare a structure
using LIKE, the STRUCT contains a pointer to a similar STRUCT that contains access
information.) You store and retrieve STRUCT data as text; TACL stores the data in an
internal format and performs translation to and from the internal format as needed. You
can redefine a STRUCT and specify new access information for your data.
A structure in TACL can contain up to 5000 bytes of data.
V a ria ble s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-13
V a ria ble s
Considerations
The use of LIKE conserves variable space, because like structures and
substructures use the same structure-accessing information. Accessing
information is not part of a particular structure. The original structure and all like
structures merely point to the access information. TACL automatically releases
accessing information when it is no longer needed.
Structure-accessing information must be in the same segment as any structure
using it. TACL automatically copies the information to the segment where it is
needed, even if it has copied it before; this means that if you have a segment full of
definitions to be used by structures in another segment, you should define one
structure in that other segment like the original definition, then define any additional
structures like that first copy. This precaution ensures that there is only one copy of
the structure-accessing information.
If structure A is defined to be like structure B, changing the definition of B later
does not change the definition of A because, although it creates new structureaccessing information for B, A still refers to the original accessing information.
When manipulating structures in TACL, use data in an appropriate external format.
For instance, store and retrieve file names in STRUCTs in external format,
although TACL maintains file names in STRUCTs in internal format. In TACL, there
is a difference between 12 integers and an internal-format file name; each occupy
the same amount of storage, but their representation to a TACL programmer is
different.
TACL aligns structures on word boundaries and allocates storage within a
structure:
BYTE and CHAR data items in a structure are byte-aligned; all other items are
multiple-word items and are word-aligned.
V a ria ble s
BYTE
CHAR
CRTPID
DEVICE
DEVICE
ENUM
FNAME
FNAME32
INT
INT2
INT4
PHANDLE
SSID
STRUCT
SUBVOL
TRANSID
TSTAMP
UINT
USERNAME
BOOL
UINT
BOOL
is a 16-bit signed value that is either true (represented by -1) or false
(represented by 0).
BYTE
is an 8-bit unsigned binary integer; its value is in the range 0 to 255.
CHAR
is an 8-bit ASCII character.
CRTPID
is a 4-word internal-format process ID.
DEVICE
is a 4-word internal-format device name.
ENUM
is a 16-bit signed, enumerated value whose range is defined by the subsystem
and depends on the token number; its value is in the range -32768 to +32767,
and its format is the same as for INT type.
FNAME
is a 12-word internal-format file name for a disk file, process, or device, in the
same form as that produced by the FNAMEEXPAND procedure.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-15
V a ria ble s
FNAME32
is a 16-word internal file name of the form used by the Distributed Name
Service (DNS), consisting of a 4-word internal-format node name followed by a
12-word internal-format local file name.
INT
is a 16-bit signed integer; its value is in the range -32768 to +32767.
INT2
is a 32-bit signed integer; its value is in the range -2147483648 to
+2147483647.
INT4
is a 64-bit signed integer; its value is in the range -9223372036854775808 to
+9223372036854775807.
PHANDLE
is a 10-integer external representation of a process handle. The ten unsigned
integers are separated by periods. Each integer can range from 0 to 65535.
SSID
is a 6-word SPI subsystem identifier; its external representation is one to eight
alphanumeric characters or hyphens giving the subsystem owner, followed by
a period (.) separator, an integer subsystem number or a subsystem name, a
period separator, and an integer version number.
SUBVOL
is the first two parts (8 words) of an internal-format local file name; it can be a
disk volume and subvolume, a device name and subdevice name, or a process
name and its first qualifier name. The qualifier name can be from one to seven
alphanumeric characters, preceded by a number sign. The first character must
be alphabetic.
TRANSID
is a 64-bit HP NonStop Transaction Management Facility (TMF) subsystem
internal-format transaction ID.
TSTAMP
is a 64-bit, microsecond-resolution Julian timestamp (Greenwich mean time) or
an elapsed-time value in microseconds.
UINT
is a 16-bit unsigned integer; its value is in the range 0 to 65535.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-16
V a ria ble s
USERNAME
is an 8-word internal-format user name in the same form as that produced by
the USERIDTOUSERNAME procedure. identifier is a name, 1 to 32 characters
in length, which can include alphanumeric, underscore, and circumflex
characters; the first character cannot be numeric.
identifier
is a name, 1 to 32 characters in length, which can include alphanumeric,
underscore, and circumflex characters; the first character cannot be numeric.
VALUE initial-value
specifies the initial value for the field and the value to be given to the field anytime
that the STRUCT is cleared. A STRUCT, like any variable, is cleared by setting it to
nothing:
#SET struct
If you omit VALUE, the default initial value depends on the type of the item:
Numeric items are set to binary zero; other items are set to ASCII spaces.
For CHAR items, initial-value is a character sequence that can appear in
either of two formats:
If you include VALUE for a CHAR item, but supply an incorrect number of initial
values, TACL returns a syntax error.
For all other items, initial-value is a space-separated list of values
appropriate to the type of the item. End-of-line may also be used as a separator.
The list ends when the semicolon is reached. If initial-value does not supply
enough data for all occurrences of the item, TACL supplies appropriate default
initial values for the remaining occurrences.
To be included in a CHAR value, regardless of whether it is enclosed in quotation
marks, a TACL metacharacter must be input under PLAIN or QUOTED format, or
must be preceded by a tilde: ~[, ~|, ~], ~{, ~}, ~==, or ~~. The tilde is not stored in
the structure.
Considerations
These considerations apply to the use of a STRUCT variable to store process
information:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-17
V a ria ble s
To display a process handle, you can use the OUTVAR command or #OUTPUTV
built-in function. In addition, the #VARIABLEINFO built-in function with option
TYPE returns type PHANDLE for a process handle field in a STRUCT. You can
specify a structure or an array within a structure. For more information, see the
next two subsections.
V a ria ble s
For CHAR items, initial-value is the same as that defined for a simple data item (in
the previous subsection). If you include VALUE but supply an incorrect number of
initial values, TACL returns a syntax error.
For all other items, initial-value is a space-separated list of values appropriate to
the type of the item. End-of-line may also be used as a separator. The list ends
when the semicolon is reached. If initial-value does not supply enough data for all
occurrences of the item, TACL supplies appropriate default initial values for the
remaining occurrences.
Consideration
TACL treats a data item declared without bounds as though it had been declared with
bounds (0:0, which is one byte long).
Example
This example declares a structure containing various arrays:
[#DEF arrays STRUCT
BEGIN
INT array^1 (1:100);
INT array^2 (-5:-1) VALUE 1 2 3 4 5;
INT array^3 (-90:90);
CHAR array^4 (0:16) VALUE "This is a ""VALUE""";
END;
]
Declaring a Substructure
A substructure declaration associates an identifier with a structure embedded within
another structure or substructure. The syntax for a substructure declaration is:
STRUCT identifier [ ( lower-bound : upper-bound ) ] ;
structure-body
identifier
is a name, 1 to 32 characters in length, which can include alphanumeric,
underscore, and circumflex characters; the first character cannot be numeric.
lower-bound
is a value in the range -32768 to +32767 that defines the number of the first
array element of an array data item; it must be less than or equal to upperbound.
upper-bound
is a value in the range -32768 to +32767 that defines the number of the last array
element of an array data item; it must be greater than or equal to lower-bound.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-19
V a ria ble s
structure-body
contains the declarations that define the substructure.
Considerations
You can nest substructures to any practical level. For additional information on
substructure alignment, see Declaring a Structure Body on page 4-13.
TACL treats a data item declared without bounds as though it had been declared
with bounds (0:0, which is one byte long).
To define data that appears in a structure but is not used by your program
To document word-alignment padding bytes that would be inserted by TACL
To provide placeholders for unused space
You can access a FILLER item only by accessing a structure containing it; if you do
access this structure, TACL treats the FILLER item as type CHAR.
Example
This example shows sample FILLER declarations:
[#DEF sample STRUCT
BEGIN
CHAR byte (0:2);
FILLER 1; == Documents word-alignment pad byte
INT word1;
INT word2;
FILLER 30; == Placeholder for unused space
INT2 integer32;
END;
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-20
V a ria ble s
V a ria ble s
END;
]
aa
b
aa
b
aa
b
c
y
4. This example shows storage for substructure occurrences that begin on word
boundaries because the substructure starts with an INT item (a^a).
[#DEF t1 STRUCT
BEGIN
CHAR x;
STRUCT t2 (0:1);
BEGIN
INT a^a;
INT b;
CHAR c;
END;
INT y;
END;
]
x
a^a
b
c
a^a
b
c
y
V a ria ble s
LIKE startup_message;
END;
]
Redefining a Structure
A redefinition declares a new name and description for an existing data item or
substructure. This functionality is similar to a redefine in TAL or a variant record in
Pascal. The syntax for a redefinition declaration is:
type identifier [ ( lower-bound : upper-bound ) ]
REDEFINES previous-identifier ;
[ structure-body ]
type
is one of the data types defined in Declaring a Simple Data Item on page 4-15.
identifier
is the name of the new data item that redefines an existing data item, at the same
structure-nesting level. The new item can be a simple data item, an array data
item, or a substructure.
lower-bound
is a value in the range -32768 to +32767 that defines the number of the first array
element of an array data item; it must be less than or equal to upper-bound.
upper-bound
is a value in the range -32768 to +32767 that defines the number of the last array
element of an array data item; it must be greater than or equal to lower-bound.
previous-identifier
is the name of a data item previously declared at the same structure nesting level.
You cannot specify array bounds with this name.
structure-body
is used only when redefining a substructure ( type is STRUCT); it contains the
declarations that describe the new substructure.
Considerations
A redefinition always starts at element zero of the previous item regardless of the
bounds of that item; this means that the previous item must at least have an
element 0.
The data area of a redefinition must be exactly the same as, or entirely within, the
data area of the previous item.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-23
V a ria ble s
The new item must be capable of the same alignment as the previous item.
Caution. Data stored by one definition might not be readable when retrieved by using another
definition. TACL does not ensure that the data being retrieved is valid under the definition by
which it is being retrieved.
Examples
Examples of redefinition declarations follow.
1. This example redefines part of an INT array as an INT2 array. The redefinition
begins at a(0):
[#DEF s STRUCT
BEGIN
INT a(-2:3);
INT2 b(1:2) REDEFINES a;
END;
]
Definition
Redefinition
a(-2)
a(-1)
a(0)
b(1)
a(1)
a(2)
b(2)
a(3)
Definition
Redefinition
int1
chr1
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-24
V a ria ble s
Definition
xx
Redefinition
yy
xx
zz
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-25
V a ria ble s
If you are storing data in a substructure or array (except of type CHAR) you must
enter it into a space-separated list of representations appropriate for the types of
those items. If the data is shorter than the substructure or array, TACL sets
remaining numeric binary items to binary zero and sets other types of items to
spaces.
Data that is being stored into an array of type CHAR is not separated by spaces
and may even include spaces. If the data is exhausted, TACL sets the remainder of
the array to spaces.
V a ria ble s
You can use the #SETV built-in function to copy structures (as well as other types of
variables). The output variable level must already exist; its original type and data are
lost. The output variable level becomes a structure identical to the input structure and
has its own copy of the data.
This is a brief summary of what you can and cannot do when copying STRUCT data.
Suppose you had created this STRUCT to contain an escape control character (ASCII
27) followed by a vertical-line character; this combination clears the screen when sent
to 653x terminals. To assign the data to a text variable for ease of use, enter:
[#DEF makecs STRUCT
BEGIN
BYTE b(0:1) VALUE 27 73;
CHAR c(0:1) REDEFINES b;
END;
]
#PUSH cs
To do so, you could use one of these #SET calls:
#SET cs [makecs:c(0:1)]
#SETV cs "[makecs:c(0:1)]"
but you could not use this statement:
#SETV cs makecs:c(0:1)
You can assign structures or substructures with #SETV, but not specific data items of a
structure. (If you had defined B and C as substructures of MAKECS, you could use the
preceding function call, but it would change CS from a simple text variable to a
STRUCT identical to MAKECS). Nor could you use:
#SETBYTES cs makecs:c(0:1)
because CS is a text variable and #SETBYTES requires that both source and
destination be structured variables.
If you had a STRUCT defined as:
[#DEF arrays STRUCT
BEGIN
INT array^1 (1:100);
CHAR array^2 (0:16) VALUE "This is a ""VALUE""";
END;
]
you could copy specific elements of array^1 or array^2 to another variable in this way:
#SET halfnums [arrays:array^1(1:50)]
#SET firstword [arrays:array^2(0:3)]
Data retrieved from a structure item is presented in a standard representation
appropriate for the type of that item.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-27
V a ria ble s
D IR E C T O R Y V a ria ble s
These examples are based on the structure defined in Setting or Altering Structured
Data on page 4-25.
To access a data item, surround the structure and item names in square brackets. For
example:
== Access elements in a structure
[tacl^files:file(2):name] == yields taclbase
[tacl^files:file(1)] == yields tacl 100
== Access the entire structure structure
[tacl^files] == yields tacl 100 taclbase 101 taclinit 101
== Distribute structure items into variables
#SETMANY prg prgcd lib libcd mac maccd , [tacl^files]
== Copy a substructure to a substructure
#SET tacl^files:file(1) [tacl^files:file(2)]
Caution. Use care when moving data between structures and variables of other types unless
those variables are used with #SERVER or #REQUESTER or are merely temporary variables
for copying the data of one structure to another. TACL interprets data differently for STRUCT
variables than for other types of variables. For example, if you process such data with #DELTA
while the data is in a variable that is not a structure, #DELTA interprets any bytes holding
binary zero as line end characters, and reshapes the data into multiple lines when putting it
back into a variable. In short, do not process structure data outside a structure except to
perform I/O operations with it.
To fill one STRUCT with data already present in another structure, use #SETBYTES.
You can use the #SETV built-in function to copy structures (as well as other types).
The output variable must already exist. After the data has been copied, the original
type and data of the output variable is lost; the variable becomes a structure like the
input structure and has its own copy of the data.
DIRECTORY Variables
Directory variables allow you to specify a hierarchical organization for variables that
reside in a segment file; directories can contain directories, which in turn can contain
other directories. The maximum nesting depth for directories is 16 levels. The root of
the tree is the home (:) character. TACL supplies the :UTILS directory, which includes
the :UTILS:TACL directory where all TACL variables reside.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-28
V a ria ble s
Directory variables allow you to keep your variables grouped together in a segment file,
for your use or for sharing with other users. Segment files are explained in Section 5,
Statements and Programs.
If the partial path name is being supplied to #DEF, #PUSH, PUSH, or ?SECTION
(in a library), TACL behaves as though the partial path name were preceded by the
directory named in the most recent HOME command. For example,
HOME :a:b
PUSH c
is equivalent to
PUSH :a:b:c
If the partial path name is being supplied to any other command, TACL acts as though
the partial path name were preceded by the directory named in the most recent HOME
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-29
V a ria ble s
command, and then successively by the directories named in the most recent USE
command, until it finds a variable by that name. For example,
HOME :a:one
USE :b :b:two : :c:d:three
OUTVAR d
outputs the first one of these that it finds:
:a:one:d
:b:d
:b:two:d
:d
:c:d:three:d
For additional information about directories supplied with the TACL software, see
Section 6, The TACL Environment.
DELTA Variables
DELTA variables contain a sequence of commands that are understood by the #DELTA
low-level character editor. Most #DELTA capabilities can be performed using stringhandling and character-handling commands and functions. For more information about
#DELTA, see #DELTA Built-In Function on page 9-111.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
4-30
A function call
A directive
This section describes the syntax for TACL statements and directives, and then
discusses how to create TACL programs, handle completion codes, and process
errors.
For additional examples of TACL programs, see the TACL Programming Guide.
Function Calls
This subsection describes each of these types of statements, and includes a list of
arguments that are common to built-in TACL functions.
A function call has this syntax:
function-call [ argument [ argument ... ] ] [ enclosure ]
[ comment]
function-call
is the name of a TACL command or built-in function, or a user-defined TACL program.
The syntax for each command is listed in Section 8, UTILS:TACL Commands and
Functions. The syntax for each built-in function is listed in Section 9, Built-In Functions
and Variables.
You must enclose the function call in square brackets if:
You want to use the expansion of the function call for further processing.
The function call includes an enclosure.
The function call spans more than one line.
The function call requires brackets to process an argument that references a
multiple-line variable. (Some function calls, such as #OUTPUT, expand their
arguments and use only the first line unless you surround the function call with
square brackets. TACL then tries to execute the second and following lines of the
expanded variable.)
If none of the foregoing are true, the function call need not be enclosed in brackets.
argument
is text, a string, a function name, or other construct as defined by the function call.
If you supply a function name as an argument, the name must be enclosed in
square brackets. For definitions of text and strings, see Section 2, Lexical
Elements.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-1
S ta te m en ts an d P ro g ra m s
F un ctio n C a lls
enclosure
specifies that TACL defers expansion of enclosed code until a specific path is
selected. (See Considerations.) An enclosure can be used only in a #CASE, #DEF,
#IF, or #LOOP built-in function call. An enclosure consists of one or more pairs of
labels and text:
label
A label is a text constant or a space-separated list of text constants, enclosed
in vertical lines. Each label precedes and identifies a given portion of text
(which may be empty).
The text within the vertical lines depends on the type of statement; for
example, the label used with the #DEF built-in function is |BODY|.
text
is a string of text that can include one or more function calls as defined
previously. TACL expands this text if the associated label is selected by the
condition in the controlling #CASE, #DEF, #IF, or #LOOP built-in function. Any
square brackets within an enclosure must balance. The last enclosure within
the controlling function call is terminated by the right square bracket (]) that
ends the function call.
comment
is a valid comment, initiated with double equal sign characters (==) or surrounding
braces ({}), which can include text. (The COMMENT command is a function call.)
Considerations
Note that function-call can be a built-in function or command supplied in the TACL
software or a user-defined TACL program; all are handled in the same manner.
When you enter a program name (such as RELOAD or USERS) as your function
call, TACL performs an implicit RUN command. TACL starts the program and then
provides the new process with the parameters you entered after the program
name. The process then carries out your instructions.
You can place more than one function call on a physical line. To separate the
statements, use a logical end-of-line marker (~;).
TACL interprets each line or logical line (~;) as the end of a statement unless:
There are unbalanced left square brackets, in which case TACL processes
lines until all brackets are balanced.
The line ends with a continuation character (&), in which case TACL treats the
next line as a continuation of the first line.
For information about how TACL interprets each line, see How TACL Interprets
Statements on page 5-11.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-2
S ta te m en ts an d P ro g ra m s
F un ctio n C a lls
Example
This example shows an #IF built-in function call with |THEN| and |ELSE| labels:
[ #IF x > 3 |THEN|
#OUTPUT Incorrect number
|ELSE|
#OUTPUT x = [x]
]
File-Name Arguments
For file-name arguments, these guidelines apply:
TACL creates a file name based on what you specify and what the current defaults
are. To specify a file that is not in the current default subvolume (or volume),
include the appropriate subvolume (or volume) name. If you do not specify the
node name, then TACL uses the current default system. For example, if your
current defaults are \LOCAL.$WORK.MINE and you want to specify the file
TIMING in subvolume IGNITION of volume $TUNEUP on the remote system
\AUTOS, you must specify:
\AUTOS.$TUNEUP.IGNITION.TIMING
TACL performs file-name expansion for partial file names that you specify as
arguments in calls to commands and built-in functions that accept file names. A
partial file name is one that omits the node name, volume, or subvolume of a full
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-3
S ta te m en ts an d P ro g ra m s
F un ctio n C a lls
file name. If, however, you specify a volume name, you must specify a subvolume
name. This file name is not syntactically correct:
$VOLUME.FILE
If you specify a partial file name, TACL expands the file name using the current
default names for system, volume, and subvolume where necessary. If you specify
MYFILE, for example, TACL assumes you mean the file named MYFILE in the
current default subvolume, volume, and system.
For more information about file-name expansion, see the Guardian Users Guide.
Many built-in functions accept file-name templates in place of actual file names, so
that the command or function can operate on a number of similarly named files.
For information about file-name template characters, see Section 2, Lexical
Elements.
Device-Name Arguments
TACL evaluates a device name based on what you specify and what the current
defaults are. For file-name arguments, if you do not specify a node name, then TACL
uses the current default system.
Process name
A process name identifies a process or process pair within a node. The name is an
alphanumeric string up to five characters long, preceded by a dollar sign, and can
be preceded by a node name. The first character must be alphabetic. TACL uses
process names in displays and interactive requests. For each named process or
process pair, the format is $ process-name; for example:
$ABC
\SYSTEM.$PRC12
The D-series process name is similar to a C-series process name, but a fivecharacter name is allowed for remote processes. (The syntax for D-series remote
process names matches the syntax for local names.)
TACL evaluates process names based on what you specify and what the current
defaults are. If you do not specify a node name, then TACL uses the current
default system.
S ta te m en ts an d P ro g ra m s
D irective s
Process handle
A process handle contains ten unsigned integers that identify a single named or
unnamed process among all processes that are running or have run in one or more
system nodes. The process handle is an internal form of identification for a process.
System messages, completion code STRUCTs, and SPI buffers contain process
handle information.
Note. The format of a process handle is defined by the TACL software and is subject to
change in future RVUs.
TACL creates a process name based on what you specify and what the current
defaults are. If you do not specify a node name, then TACL uses the current default
system.
DEFINEs as Arguments
A number of TACL functions accept DEFINEs as arguments. A DEFINE is a named set
of attributes and associated values. In a DEFINE (as with an ASSIGN command), you
can specify information to be communicated to processes you start. The operating
system (file system or I/O processes) usually processes DEFINEs, while application
programs or run-time libraries process ASSIGNs.
TACL stores DEFINEs in its process file segment (PFS) and can propagate them to
processes you start. Some TACL functions permit you to use templates in place of
actual DEFINE names. For information about DEFINE templates, see Section 2,
Lexical Elements Commands and built-in functions that support DEFINEs are
identifiable by the appearance of DEFINE or DEFMODE in their titles. For more
information about DEFINEs, see individual command and function descriptions in this
manual, the TACL Programming Guide, the Guardian Programmers Guide, and the
Guardian Users Guide.
Directives
TACL directives are for use only in files that contain TACL statements. There are four
types of directives:
?BLANK
?FORMAT
?SECTION
?TACL
S ta te m en ts an d P ro g ra m s
? B LA N K D ire ctive
?BLANK Directive
Use the ?BLANK directive to insert a blank line into a variable; this can be useful when
you load text that is to be displayed. The syntax is:
?BLANK
?FORMAT Directive
Use the ?FORMAT directive to specify how TACL interprets metacharacters in the
TACL statements following the directive. The ?FORMAT directive is similar to the
#INFORMAT built-in variable, but acts on statements in a file instead of text from the IN
file. The syntax is:
?FORMAT { PLAIN | QUOTED | TACL }
PLAIN
causes TACL to interpret metacharacters and all other characters in the file as
ordinary text. For example, braces and double equal signs are read as such and
are not interpreted as comments in PLAIN mode.
QUOTED
causes TACL to interpret metacharacters as metacharacters (the same as the
TACL option), unless text with metacharacters is enclosed in quotation marks. In
this case, TACL treats metacharacters as if they were ordinary text (tildes are not
needed).
TACL
causes TACL to interpret metacharacters as metacharacters and store them in
internal notation. TACL reads square brackets as the beginning and ending of an
invocation. A vertical line indicates a label in an enclosure. TACL reads braces and
double equals as comments.
Using a tilde causes TACL to interpret the next character as plain text, rather than
a delimiter; for example, TACL reads ~[ as an ordinary open square bracket, rather
than the beginning of an invocation. To use a tilde character as text, enter it twice
(~~). The tilde has no effect on its own, but only in conjunction with other
characters.
When using the TACL format, you can put several commands on a single line by
separating the commands with a tilde and a semicolon (~;). TACL translates these
metacharacters into internal end-of-line characters.
You can also use a tilde and an underscore (~_) when ?FORMAT is set to TACL.
TACL translates this notation into an internal space, which is printed as a space if
you use the PRETTY option with #OUTFORMAT; otherwise, the tilde and
underscore are treated as ordinary characters.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-6
S ta te m en ts an d P ro g ra m s
? F O R M A T D ire ctive
Considerations
The ?FORMAT value for a library file is set to TACL at every ?SECTION directive.
The ?FORMAT value for a macro or routine file that starts with a ?TACL directive is
set to TACL at the beginning of the file.
Example
This example shows the effects of the ?FORMAT directive:
?SECTION this^section ROUTINE
==
== PLAIN format allows a multiple-line #OUTPUT function to
== output text containing special characters without having
== to use tildes
==
#SET #OUTFORMAT PLAIN == Set display format to PLAIN
[#OUTPUT Using ?FORMAT PLAIN:
?FORMAT PLAIN
+------------------------+
| COMMENT [ <argument> ] |
+------------------------+
?FORMAT TACL
]
#OUTPUT
[#OUTPUT Using ?FORMAT QUOTED:
?FORMAT QUOTED
"+------------------------+"
"| COMMENT [ <argument> ] |"
"+------------------------+"
?FORMAT TACL
]
#OUTPUT
#OUTPUT
#OUTPUT ?FORMAT TACL, with quotes: "[#MYTERM]"
#OUTPUT ?FORMAT TACL, without quotes: [#MYTERM]
#OUTPUT
?FORMAT PLAIN
#OUTPUT ?FORMAT PLAIN, with quotes: "[#MYTERM]"
#OUTPUT ?FORMAT PLAIN, without quotes: [#MYTERM]
#OUTPUT
?FORMAT QUOTED
#OUTPUT ?FORMAT QUOTED, with quotes: "[#MYTERM]"
#OUTPUT ?FORMAT QUOTED, without quotes: [#MYTERM]
#OUTPUT
?SECTION next^section ROUTINE
== Format reverts to TACL because this is a new section
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-7
S ta te m en ts an d P ro g ra m s
? S E C T IO N D ire ctive
?SECTION Directive
Use the ?SECTION directive to signal the beginning of a variable definition in a file.
This directive allows you to create a library that contains definitions for many variables.
The syntax of the directive is:
?SECTION variable-name variable-type
variable-name
specifies the name associated with the following lines of text. For information about
valid variable names, see Section 4, Variables.
variable-type
specifies the type of TACL variable: TEXT, ALIAS, MACRO, ROUTINE, STRUCT,
DIRECTORY, or DELTA.
Considerations
To cause TACL to interpret or execute the contents of the file, use the LOAD
command or #LOAD built-in function to load the contents into memory. This
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-8
S ta te m en ts an d P ro g ra m s
?T A C L D ire ctive
example shows how to load two libraries, retaining only one level of each variable
in the libraries:
17> LOAD /KEEP 1/ mykeys mymacs
?TACL Directive
Use the ?TACL directive to specify that the TACL statements following the directive in a
file are the contents of a TACL variable. The syntax of the directive is:
?TACL variable-type
variable-type
specifies the type of TACL variable: TEXT, ALIAS, MACRO, ROUTINE, STRUCT,
DIRECTORY, or DELTA.
Considerations
The ?TACL directive, if specified, must be the first line of the file.
To cause TACL to interpret or execute the contents of the file, type the file name.
For additional information about creating and accessing a file with the ?TACL
directive, see Creating Program Files on page 5-12.
TACL Programs
A program consists of one or more statements. You can enter the statements
interactively or store them in a file. This subsection contains information about TACL
programs:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-9
S ta te m en ts an d P ro g ra m s
Program Structure
When you write a TACL program, you define the program as a type of TACL variable.
There are four types of variables that can contain executable statements: TEXT,
MACRO, ROUTINE, and ALIAS. A program can contain of one or more TACL
statements:
A directive, ?TACL or ?SECTION, that indicates that the following lines define a
program.
A #FRAME call that defines a local environment.
A series of #PUSH or #DEF statements that define data variables and
subprograms. (TACL does not require you to place definitions at the start of a
program, but placing definitions at the start can increase readability of the
program.)
Additional TACL statements; the main body of the program.
An #UNFRAME or #RESET FRAMES call if the program called #FRAME earlier.
TACL is an interpretive language; you do not compile or bind TACL programs. TACL
programs execute as part of your interactive TACL process unless you direct them to
run independently (in the background).
Sample Program
This program, of type macro, purges a file:
?TACL MACRO
#FRAME == Establish a local environment for variables
#PUSH err == Declare a variable called "err"
== Set err to the result of the #PURGE function:
#SET err [#PURGE %1%]
== Display the results of the purge operation:
[#IF NOT err |THEN|
#OUTPUT Purge of file %1% complete!
|ELSE|
#OUTPUT Error [err]
]
#UNFRAME == Delete the local environment
A macro accepts positional arguments; %1% refers to the first argument supplied when
you run the program.
To run this program, type the name of the file that contains the TACL statements,
followed by the name of an existing file that you want to purge. If, for example, the
statements are stored in a file called PRG, you would type this to purge a file called
TEMP:
18> PRG TEMP
Purge of file TEMP complete!
19>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-10
S ta te m en ts an d P ro g ra m s
H o w T A C L In terp re ts S ta te m e n ts
If you try to purge TEMP a second time, TACL returns an error message:
19> PRG TEMP
Error 11
20>
An error 11 indicates that the file was not found:
20> Error 11
011 file not in directory or record not in file, or the
specified tape file is not present on a labeled tape
S ta te m en ts an d P ro g ra m s
Very large macros or routines. As a rule, macros should never exceed 15,000
bytes after dummy argument substitution; routines should never exceed 15,000
bytes. Nesting reduces these numbers further.
Uncontrolled nesting of macros. (If, however, you construct a recursive macro so
that it invokes itself in its last statement, each instance of the macro vanishes from
the text buffer before the next one begins and does not increase the contents of
the text buffer.)
Matching too many file names with the #FILENAMES function. TACL stores the
information in the text buffer before displaying it. Loading too much data (such as
large subvolumes of file names).
Using #CHARxxx, #LINExxx, or #DELTA built-in functions on data larger than
15,000 bytes.
One program in an edit file, executed by referencing the file name. The first line
must be a ?TACL directive.
Several programs in a single edit file, known as a library file, executed by loading
the file into variables and then referencing the name of the variable (defined in the
code). A library file can also contain other types of variables. Each variable starts
with a ?SECTION directive that assigns a name to the variable.
One or more programs in a segment file, executed by attaching the file (making
them accessible to TACL) and then referencing the variable name associated with
the program.
You can set up your TACL environment so that it loads variables from edit files or
segment files automatically at logon time.
S ta te m en ts an d P ro g ra m s
S ta te m en ts an d P ro g ra m s
partial code interpretation, the greater the number of variables you use regularly, the
more efficiency you can gain by using personal segment files instead of loading the
variables into the default segment.
There are also several built-in functions that manage segment files: #SEGMENT,
#SEGMENTINFO, and #SEGMENTVERSION return information about segment files,
and #SEGMENTCONVERT converts a segment file from C20 formats to formats of
segment files created on an RVU of TACL released at C20 or after. (Later RVUs of
TACL are different from earlier RVUs because of the addition of the international
character set).
For additional information about the creation and use of segments, see individual
command and function descriptions in Section 8, UTILS:TACL Commands and
Functions and Section 9, Built-In Functions and Variables respectively.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-14
S ta te m en ts an d P ro g ra m s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-15
S ta te m en ts an d P ro g ra m s
If the CPU on which your TACL process is running fails while you are in the act of
detaching a private segment file, the segment file may be corrupted. TACL detects
corruption of segment files and prevents their reuse. If this happens to one of your
segment files, you must purge it and re-create it.
In general, TACL segment files created by previous RVUs of TACL do not have to be
rebuilt; however, if an attempt is made to use an incompatible segment file, TACL will
give a specific error message. Rebuilding is always possible from the original libraries
without change, but there is no guarantee that you will be able to decompose a
segment file into its original libraries.
S ta te m en ts an d P ro g ra m s
TACL defines both variables when you log on, and the variables remain unless you
pop (delete) them. The default values are zeros for numeric items and spaces for text
items.
TACL sets specific items within these STRUCT variables whenever you try to start a
process, whenever you successfully start a process, and whenever a process you
started terminates (successfully or otherwise). Whenever TACL sets these variables,
their previous contents are lost. For information about the contents of these variables,
see:
S ta te m en ts an d P ro g ra m s
S ta te m en ts an d P ro g ra m s
REDEFINES z^msgnumber;
BEGIN
CHAR byte(0:1);
END;
PHANDLE z^process^handle;
INT4 z^cputime;
INT z^jobid;
INT z^completion^code;
INT z^termination^code;
INT z^killer^craid;
REDEFINES z^termination^code;
SSID z^subsystem;
PHANDLE z^killer;
INT z^termtext^len;
STRUCT z^procname;
BEGIN
INT zoffset;
INT zlen;
END;
INT z^flags;
INT z^reserved(0:2);
STRUCT z^data;
BEGIN
CHAR byte(0:111);
END;
STRUCT z^termtext
REDEFINES z^data;
BEGIN
CHAR byte(0:111);
END;
STRUCT z^procname^
REDEFINES z^data;
BEGIN
CHAR byte(82:193);
END;
END;
]
If you incur a syntax error while trying to start a process, TACL sets
z^completion^code to 4.
If a process fails to start, TACL sets z^completion^code to 4.
If you successfully start a process, TACL sets z^completion^code to 0.
The field :_completion^procdeath:z^procname:zoffset contains the byte
offset of the process name. The process name will always be within the substructure
z^data, so the offset will always be between 82 and 193.
When a process is named, :_completion^procdeath.z^procname.zlen is
greater than zero.
Otherwise, :_completion^procdeath.z^procname.zlen equals zero and
:_completion^procdeath:z^data contains spaces.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-19
S ta te m en ts an d P ro g ra m s
PMSG is ON.
:_COMPLETION:MESSAGECODE is -5 (STOP) and
:_COMPLETION:COMPLETIONCODE is not 0 and not 6 (stopped externally).
:_COMPLETION:MESSAGECODE is -6 and :_COMPLETION:COMPLETIONCODE is
not 5 and not 6 (stopped externally).
:_COMPLETION:TERMINATIONINFO is not 0 and
:_COMPLETION:COMPLETIONCODE is not 6 (stopped externally).
:_COMPLETION:TEXTLENGTH is not 0.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-20
S ta te m en ts an d P ro g ra m s
H a nd lin g T A C L E rrors
Example
Description
Syntax error
Expecting an
existing
variable,
unqualified
TACL error
*ERROR*
Security
Violation
Error During
a function
call
None
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-21
S ta te m en ts an d P ro g ra m s
H a nd lin g T A C L E rrors
Example
Description
Error defined
by program
None
Fatal error
ABENDED:
$TCL2 CPU
TIME
0:00:00.013
Termination
Info 14 TACL
fatal error:
Couldn't open
TACL IN
Internal error
ABENDED:
$TCL4 CPU
TIME
0:00:00.052
Termination
Info 18 TACL
internal error:
Initialize.100
TACL programs can check for function call errors immediately after a function call. To
handle other types of errors, see the discussion about exception handlers in the TACL
Programming Guide.
TACL can generate one type of EMS error: Error 66, an I/O error.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
5-22
For information about the use of TACL with other subsystems, see the TACL
Programming Guide. Section 7, Summary of Commands and Built-In Functions,
provides an overview of TACL commands and functions.
Installation Instructions
TACL is now also delivered with HIGHPIN set to ON. To get TACL with HIGHPIN set to
ON, follow the below steps:
1. Run this command:
FUP RENAME <install-vol>.<SYSnn>.TACL, TACLLOW
2. Run this command:
FUP DUP <install-vol>.ZTACL.TACLH,<install-vol>.<SYSnn>.TACL
3. Restart all TACL processes..
Note. F ro m th is S P R th e Z T A C L su b vo l w ill b e a va ila b le , u nd e r w h ich th e T A C LH file fo r
H IG H P IN is p rese n t.
T he T A C L E n viron m en t
S ta rting a T A C L P ro ce ss
TACLBASE, an edit file that contains the same functionality as TACLSEGF. This
file resides on the same subvolume as the TACL file. Along with providing
functionality, TACLBASE provides a readable source of examples of TACL
programs.
TACLCOLD, a segment file that TACL uses when running as the coldload
command interpreter. TACL creates this file or reuses it as a way of reducing the
chance that the coldload TACL will fail due to lack of disk space at startup.
CPRULES0 and CPRULES1, which define the character set in use by TACL.
CPRULES0 is the default set.
In addition to the preceding list of files, there are utility programs that assist TACL in
performing certain operations. Each program is in a separate program file in
$SYSTEM.SYSnn or $SYSTEM.SYSTEM. These programs:
A TACL process:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-2
T he T A C L E n viron m en t
L og gin g O n
Processes that run at high PINs cannot open and write to processes that do not allow
high-PIN openers. For example, a TACL process that runs at a high PIN cannot open a
process on a C-series node. Similarly, a TACL process on a C-series node cannot
open a high-PIN process. This limitation applies to any operation that accesses
process identifier information, such as alteration of priority. If you start a process and
try such communication with the new process, the new process terminates.
Logging On
To access a TACL process, you must log on. Before you log on, the only commands
TACL accepts are LOGON, FC, !, PAUSE, and TIME. If the system runs Safeguard
software, Safeguard can be set up so that it authenticates your user ID and requests
that TACL start logged-on. In this case, you do not need to log on to TACL.
TACL Initialization
When you log on, TACL creates a private segment file for you and invokes TACLINIT
(usually $SYSTEM.SYSnn.TACLINIT). TACLINIT begins initialization of TACL and then
searches in the same subvolume for the TACLSEGF segment file, which it attaches
and makes available under the directory :UTILS:TACL. Directories are described in
Using Directories on page 6-9.
TACL searches for TACLLOCL first in the SYSnn of the TACL PROGRAMFILE, and
then in $SYSTEM.SYSTEM.
You can ensure that there is always a system load recovery path by placing a
TACLLOCL in each SYSnn. If a TACLLOCL change causes any problem, reload the
system from the original SYSnn.
This method also offers a superior organizational scheme, because a TACLLOCL for
different system images often needs to have different TACL statements. Rather than
having complex version condition checking, each system image version can now have
its own TACLLOCL file.
If it finds the file, TACL invokes it as a macro. At this point, if your default subvolume
contains a TACLCSTM file, TACL invokes it as a macro. Your TACLCSTM file, which
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-3
T he T A C L E n viron m en t
contains any commands you supply, can include a request to load all your personal
command definitions.
TACL passes one argument to TACLCSTM, indicating whether the loading of
TACLBASE was suppressed because you are the most recent user to log off from this
TACL and are now logging back on. (The same segment is still in effect.) The
argument is nonzero if loading was suppressed, and zero if it occurred.
The TACLLOCL of the installation or your individual TACLCSTM can also create
directories for additional segment files.
CPRULES0 and CPRULES1 define the character set in use by TACL. CPRULES0 is
the default set. When starting a TACL process, if #CHARACTERRULES is empty after
TACLLOCL has been invoked, the TACL process looks for CPRULES0. TACL
searches for CPRULES0 in $SYSTEM.SYSTEM. If CPRULES is not found there, then
TACL searches the same volume and subvolume in which the TACL program file
resides (usually, $SYSTEM.SYSnn). If a CPRULES file does not exist when a user
logs on and the TACL process tries to access a CPRULES file, the TACL process
issues a warning that it is using its own set of rules (that are encoded in the TACL
program file).
TACL sets the initial terminal state to:
ECHO on
Single spacing
Post spacing
Conversational mode
Note. If a backup TACL process takes over at a later time, TACL initializes the terminal state
to the preceding values unless the TACL process has a descendent process that continued to
run during the processor switch. In this case, TACL does not initialize the terminal state values.
After your TACL process completes initialization and you log on, you can:
Store a text, macro, or routine variable in its own file and invoke it by file name
Store one or more programmatic variables in a library file and issue a LOAD
command or #LOAD call to make the variables accessible to TACL
For more information about these procedures, see Section 5, Statements and
Programs.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-4
T he T A C L E n viron m en t
S ta rtin g N e w P ro ce sse s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-5
T he T A C L E n viron m en t
S ta rtin g N e w P ro ce sse s
These conditions must be met before TACL can start a process at a high PIN:
The HIGHPIN option for the code file must be enabled at compile or bind time
Either the RUN /HIGHPIN ON/ option or the #HIGHPIN built-in variable (or both)
must be ON
There must be a high PIN available
Table 6-1 describes how TACL resolves each combination of HIGHPIN settings. A
dash (-) indicates that the option is not specified.
Table 6-1. Results of HIGHPIN Settings
Parent TACL
Runs at a
BINDER
HIGHPIN
Option
HIGHPIN
Variable
RUN or
#NEWPROCESS
HIGHPIN Option
New Process
Runs at a
Low PIN
OFF
OFF
Low PIN
Low PIN
OFF
OFF
OFF
Low PIN
Low PIN
OFF
OFF
ON
Low PIN
Low PIN
OFF
ON
Low PIN
Low PIN
OFF
ON
OFF
Low PIN
Low PIN
OFF
ON
ON
Low PIN
Low PIN
ON
OFF
Low PIN
Low PIN
ON
OFF
OFF
Low PIN
Low PIN
ON
OFF
ON
High PIN*
Low PIN
ON
ON
High PIN*
Low PIN
ON
ON
OFF
Low PIN
Low PIN
ON
ON
ON
High PIN*
High PIN
OFF
OFF
Low PIN
High PIN
OFF
OFF
OFF
Low PIN
High PIN
OFF
OFF
ON
Low PIN
High PIN
OFF
ON
Low PIN
High PIN
OFF
ON
OFF
Low PIN
High PIN
OFF
ON
ON
Low PIN
High PIN
ON
OFF
OFF
Low PIN
High PIN
ON
OFF
OFF
Low PIN
High PIN
ON
OFF
ON
High PIN*
High PIN
ON
ON
High PIN*
High PIN
ON
ON
OFF
Low PIN
High PIN
ON
ON
ON
High PIN*
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-6
T he T A C L E n viron m en t
To check the setting of the #HIGHPIN variable from an interactive terminal, type
SHOW HIGHPIN. To check the setting of the BINDER HIGHPIN option for an object
file (type 100 or 700), enter:
BIND; SHOW SET * FROM file-name
For additional information about the BINDER HIGHPIN option, see the Binder Manual.
Personal customization for one user, through the use of the TACLCSTM file
Local customization, through use of the TACLLOCL file
Customization affects all uses of TACL, not just interactive TACL sessions started from
TELNET or SSH. Customization of TACLCSTM and TACLLOCL must allow server
programs to start TACL processes without interference.
Standard server programs using background TACL processes do not tolerate
interactive queries when TACL starts. Arbitrary redefinition of standard TACL
commands or environment might also cause difficulties.
Examples of products that start background TACL processes include some HP OSM
program files, NonStop Essentials, and the SeeView Server Gateway. These products
start TACL processes either on behalf of a command from a human-computer interface
or for unattended background activities.
Customization of a particular user IDs TACLCSTM for security auditing might require
special care. A TACLCSTM file for a particular user can check the ancestor process of
the TACL process for special exceptions. For an example of this customization for a
particular user in the SUPER group, see the OSM Configuration Guide.
Personal Customization
To customize your TACL environment, you can add the following to your TACLCSTM
file:
TACLCSTM can also change your saved defaults by assigning volume and subvolume
names to the variable :UTILS_GLOBALS:TACL:_DEFAULTS_INITIAL.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-7
T he T A C L E n viron m en t
Local Customization
The TACLLOCL file provides a mechanism for environment customization for all users
on a given system (you might think of TACLLOCL as the system managers version of
TACLCSTM). This example shows a sample TACLLOCL file:
?TACL MACRO
== TACLLOCL sets up variables, macros needed for operations
RUN $system.system.opertool == defines _oper^tools variables
[#IF %1% |THEN|
== A fast logon
|ELSE|
== A slow logon
SINK [#LOAD /KEEP 1/ [_oper^tools].macrolib]
]
In the preceding example, the dummy argument %1% refers to an argument provided
by TACL when you log on; you can use this same construct in your TACLCSTM file.
The argument is true (a nonzero value) if the default segment file containing TACL
variables exists, false (zero) if TACL created a new segment file when you logged on. If
the segment file exists, loading library files is unnecessary.
Security
There exists a potential breach of security if other TACL users open your TACL
process. To limit access to your TACL process, use the #TACLSECURITY built-in
variable, described in #TACLSECURITY Built-In Variable on page 9-400.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-8
T he T A C L E n viron m en t
Logons and logoffs, including illegal logon attempts (LOGON and LOGOFF
commands)
Addition or deletion of users (ADDUSER, DELUSER programs)
Alteration of priorities at execution time (ALTPRI command)
Process startups (RUN command and #NEWPROCESS built-in function)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-9
T he T A C L E n viron m en t
A CMON configuration message, which establishes the TACL configuration for the
new process or user.
A pre-LOGON message, which allows $CMON to invoke additional security
provisions (for example, requiring a user to log on under one ID before being able
to log on under some other ID).
Using Directories
TACL organizes its variables according to purpose or product; it keeps your variables
separate from TACLBASE variables (commands) and helper variables that are used by
the TACLBASE variables and are not intended for direct use. This organization called a
directory, and is hierarchical, similar to a tree. The root of the tree is the :directory.
Directories organize variables in a hierarchy and take advantage of operating system
features that support segment files.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-10
T he T A C L E n viron m en t
UTILS_GLOBALS
user-variables
UTILS
...
ZAP
TACL
zap-globals tacl-globals
Private Segment File
Private/Read-Write
One per TACL Process
...
ZAP
TACL
zap-commands tacl-commands
Minimizes the potential for naming conflicts among variables from various sources
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-11
T he T A C L E n viron m en t
Other application products (that are part of a software RVU) can also create
directories. TACL requires you to specify where to put the associated variables or, by
default, stores them in your current home directory. (To store variables in your home
directory, your home directory must be writable.) The documentation for each product
explains how to access and use these files.
Do not create variables whose names begin with a circumflex (^) and never use, in
any way, such variables.
Do not create or use variables whose names begin with an underscore (_), except
where specifically permitted as a feature of an application program.
Do not create any variables under :UTILS.
Do not create any variables under :UTILS_GLOBALS, except where specifically
permitted as a feature of an application program.
Do not push or pop :UTILS or :UTILS_GLOBALS.
If you modify the use list, ensure that your use list always includes certain
directories necessary for the correct operation of the application program. The
USE command automatically does this for you. The list of necessary directories
depends on the application software version and must not be hard coded in your
TACL programs.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-12
T he T A C L E n viron m en t
_ E X E C U T E V a ria ble s
_EXECUTE Variables
If you try to invoke a variable that is itself a directory, TACL searches that directory for
a variable named _EXECUTE and invokes that variable instead. The _EXECUTE
variable provides an automatic mechanism for special initialization activities such as:
Displaying a banner
Establishing a frame
Pushing the use list and altering it
Creating variables
Starting servers
Opening files
Establishing an exception handler
For example:
?SECTION _execute ROUTINE
PATHCOM $XXPM;RUN XX
Some application products allow you to enter TACL commands while you are using
them. This flexibility allows you to invoke another product without leaving the first
product.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-13
T he T A C L E n viron m en t
D efau lt F ile s
Default Files
Instead of using your saved defaults, a background TACL takes on the same file-name
defaults as those of the process that started it. This procedure occurs as follows:
1. TACL saves the inherited defaults in the variable
:UTILS_GLOBALS:TACL:_DEFAULTS_INITIAL and switches to your saved
defaults (saved under your user ID on the system where the background TACL is
running). TACL saves a copy of those defaults in the variable
:UTILS_GLOBALS:TACL:_DEFAULTS_SAVED.
2. TACL invokes the specified TACLCSTM file (if any) in the same way and with the
same defaults as if you logged on explicitly. To specify a TACLCSTM file, use the
ASSIGN command in the process that starts the background TACL:
ASSIGN TACLCSTM, file-name
If file-name is not fully qualified, ASSIGN assumes the defaults in existence for
the process that issued the ASSIGN command (not the process receiving it).
To omit the TACLCSTM file, enter this; the comma indicates the absence of the
file-name field:
ASSIGN TACLCSTM,
If you do not issue an ASSIGN TACLCSTM command, the background TACL uses
your current TACLCSTM file by default.
3. After it has invoked TACLCSTM, TACL sets the defaults to the value in the variable
:UTILS_GLOBALS:TACL:_DEFAULTS_INITIAL. If you need to establish a
particular set of initial defaults, your TACLCSTM should contain coding to set
:UTILS_GLOBALS:TACL:_DEFAULTS_INITIAL accordingly.
You can read the variables in the directory :UTILS_GLOBALS (and its subdirectories),
but do not change them, except as directed in application-product documentation.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
6-14
7
Summary of Commands and Built-In
Functions
TACL provides three types of standard capabilities:
Built-in functions and variables provide information that can be used by a program.
They return information and status in the form of a result. The set of built-in
functions and built-in variables provide the fundamental, fixed set of TACL
functionality.
TACL Commands
When you log on to your system, you use TACL commands. These commands include:
RUN
Runs a process
STATUS
WHO
Commands are intended for interactive use; although you can use them in TACL
programs, commands do not typically return as much status or error information as do
functions. The commands generally display a result.
TACL commands are interpreted. Each command is a TACL variable. All commands
call TACL built-in functions.
The :UTILS:TACL directory contains all the TACL commands, including commandinterpreter commands and additional commands, programs, and functions used by
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-1
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
B u ilt-In F un ction s
TACL. For example, the :UTILS:TACL variable VOLUME refers to the command
named VOLUME that is executable by the TACL program. For more information about
directories, see Section 6, The TACL Environment.
Most :UTILS:TACL commands are available to every user. Some commands and some
utility programs, however, are restricted so that only certain users can execute them.
Restricted commands and programs can be used by these two groups:
(The terms user ID and group ID are described in the Guardian Users Guide.) The
command descriptions in Section 8, UTILS:TACL Commands and Functions indicate
whether a command or program is restricted or not.
The super ID (a user who has the user ID 255,255) can execute any command or
program reserved for group managers or super-group users.
Built-In Functions
In addition to the :UTILS:TACL commands, TACL provides built-in functions and built-in
variables that can be used for the construction of macros and routines.
TACL built-in functions cannot be changed. Built-in functions provide the basic
elements of TACL on which all other features, including TACL commands, are based.
Where built-in functions and TACL commands provide the same functionality, built-in
functions provide more error information and are slightly faster than commands. Built-in
function names start with a number sign (#), ensuring that the names you choose for
your macros or routines do not conflict with the names of built-in functions and
variables. Examples include:
#COMPAREV
#OUTPUT
#PROCESSINFO
Built-in functions also provide flow control, such as loop control and exit mechanisms.
To view a list of built-in functions, use the #BUILTINS built-in function.
Some built-in functions must be used within routines. These built-in functions (for
example, #ARGUMENT, #MORE, and #REST) provide the mechanism by which
routines evaluate their arguments and return their results. Unlike a macro, the result of
a routine is not the text of the routine itself. A routine computes a result string to
replace its invocation. A routine invokes #RESULT one or more times to produce a
nonempty result.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-2
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
If you type a built-in function that produces a result and you do not enclose it in square
brackets, TACL automatically displays the result; for example:
56> #WIDTH
#WIDTH expanded to:
80
Built-In Variables
TACL built-in variables provide basic elements of TACL on which all other features,
including TACL commands, are based. Unlike TACL commands, which can be
customized or redefined, built-in variables are always available as described in this
manual.
Built-in variable names start with a number sign (#). You can push them (the PUSH
command and #PUSH built-in function create new top levels of variables), pop them
(the POP command and #POP built-in function delete the top level of a variable),
invoke them, and assign values to them, but you cannot delete them. There are certain
other restrictions on their use, explained in individual function and variable descriptions
in Section 9, Built-In Functions and Variables.
Examples of built-in variables include:
#OUT
#PMSG
#MYTERM
This example changes the TACL output file (stored in #OUT) to a spooler location to
receive the list of built-in functions, then restores the output file to its previous identity:
96>
97>
98>
99>
#PUSH #OUT
#SET #OUT $S.#LP
#BUILTINS /FUNCTIONS/
#POP #OUT
You can use #PUSH (or PUSH) to save a copy of the existing contents of the top
variable level and #POP (or POP) to restore the previous contents to the top of the
stack. #PUSH, however, does not create such a variable, because it already exists, nor
can #POP delete the variable entirely (you get a was not pushed error if you try to
pop the first level).
In addition, pushing a built-in variable copies the pushed contents to the new top level
(the built-in variable and the pushed level then have the same value). Also, many builtin variables have default values or automatically stored values. Unlike your other
variables, which can be preserved from one TACL session to another, built-in variables
are popped completely and reset to their default values when you log off.
There are restrictions on the use of built-in variables; for example, a built-in variable
cannot be used as a variable in an #ARGUMENT function, nor can you specify an
explicit variable level (for example, #DEFAULTS.-2) for a built-in variable. The
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-3
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
S u m m a ry of F un ction a lity
descriptions in Section 9, Built-In Functions and Variables, explain the ways in which
those variables can be used.
Summary of Functionality
The remainder of this section lists commands, built-in functions, and built-in variables
by functional group; the groups are:
Note. A llT A C Lb u ilt-insa ree xe cute db yth eT A C Lp roce ss,w h ichru n son lyo nth en o d ew h e reitw asstarte d ,
re ga rd lesso fa n yS Y S T E Mco m m an d sth a ta reissu ed .T oe xe cu teab uilt-inco m m a ndo na no th e rsyste m ,yo u
m u st sta rt a n e w T A C L p ro ce ss o n th a t syste m .
Description
BUILTINS
COLUMNIZE
COMMENT
ENV
FC
FILEINFO
FILENAMES
FILES
HELP
HISTORY
INFO DEFINE
KEYS
LOADEDFILES
PMSG
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
O b ta inin g H e lp an d In fo rm a tio n
Description
PPD
SEGINFO
SHOW
SHOW DEFINE
STATUS
SYSTIMES
Displays current date and time, plus date and time of last cold load
TIME
USERS
(program)
VARIABLES
VARINFO
WHO
Table 7-2 lists built-in functions and variables that provide general help and
information.
Table 7-2. Informational Built-In Functions and Variables (page 1 of 2)
Function
Description
#BUILTINS
#COLDLOADTACL
#DEVICEINFO
#FILENAMES
#GETCONFIGURATION
#HELPKEY
#HISTORY
#KEYS
#PROCESSORSTATUS
#PROCESSORTYPE
#SEGMENTVERSION
#TACLVERSION
#TOSVERSION
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-5
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
#VARIABLES
#XFILES
#XPPD
#XLOADEDFILES
#XSTATUS
Description
ALARMOFF
(program)
COPYDUMP
(program)
Copies and compresses tape dump file or existing disk dump file into a
disk dump file
CREATE
INITTERM
LIGHTS (program)
PURGE
ALARMOFF
(program)
COPYDUMP
(program)
Copies and compresses tape dump file or existing disk dump file into a
disk dump file
CREATE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-6
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Table 7-4 lists the built-in functions and variables that support file and device handling.
Table 7-4. File and Device Built-In Functions and Variables
Function
Description
#CREATEFILE
Creates a file
#EOF
#FILEINFO
#FILEGETLOCKINFO
#IN (variable)
#INITTERM
#INPUT
#INPUTEOF (variable)
#INPUTV
#LOCKINFO
#NEXTFILENAME
#OPENINFO
#OUT (variable)
#OUTPUT
#OUTPUTV
#PURGE
Deletes a file
#RENAME
#REPLY
#REPLYV
#REQUESTER
#WIDTH (variable)
#XFILEINFO
#XFILENAMES
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-7
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Controlling Processes
Table 7-5 lists the commands that support process control.
Table 7-5. Process Control Commands (page 1 of 2)
Command
Description
ACTIVATE
ADD DEFINE
ALTER DEFINE
ALTPRI
ASSIGN
CLEAR
DELETE DEFINE
EXIT
INLECHO
INLEOF
INLOUT
Controls copying to TACL OUT file of lines sent to OUT file of inline
process
INLPREFIX
INLTO
PARAM
PAUSE
RESET DEFINE
RUN or RUND
SET DEFINE
SET DEFMODE
Controls whether DEFINEs are enabled for current TACL process and
are propagated to new processes
SET HIGHPIN
Sets the default PIN range for processes started by the current TACL
process
SET SWAP
Sets swap volume for all subsequent RUN commands (unless swap
volume is explicitly specified in a command)
STOP
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-8
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
SUSPEND
TACL (program)
WAKEUP
Table 7-6 lists the built-in functions and variables that support process control.
Table 7-6. Process Control Built-In Functions and Variables (page 1 of 3)
Function
Description
#ABEND
#ABORTTRANSACTION
#ACTIVATEPROCESS
#ALTERPRIORITY
#ASSIGN (variable)
#BEGINTRANSACTION
#CREATEPROCESSNAME
#CREATEREMOTENAME
#DEFINEADD
#DEFINEDELETE
#DEFINEDELETEALL
#DEFINEINFO
#DEFINEMODE (variable)
#DEFINENAMES
#DEFINENEXTNAME
#DEFINEREADATTR
#DEFINERESTORE
#DEFINERESTOREWORK
#DEFINESAVE
#DEFINESAVEWORK
#DEFINESETATTR
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-9
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
#DEFINESETLIKE
#DEFINEVALIDATEWORK
#EMSADDSUBJECT
#EMSADDSUBJECTV
#EMSADDSUBJECTV
#EMSGET
#EMSGET
#EMSGETV
#EMSINIT
#EMSINITV
#EMSTEXT
#EMSTEXTV
#ENDTRANSACTION
#HIGHPIN (variable)
#INLINEECHO (variable)
#INLINEEOF
#INLINEOUT (variable)
#INLINEPREFIX (variable)
#INLINEPROCESS (variable)
#INLINETO (variable)
#LOOKUPPROCESS
#MOM
#MYPID
#NEWPROCESS
Starts a process
#PARAM
#PAUSE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-10
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
#PMSG (variable)
#PROCESS
#PROCESSEXISTS
#PROCESSINFO
#SERVER
Description
ADDDSTTRANSITION
ADDUSER (program)
BACKUPCPU
BUSCMD (program)
Tells operating system that a bus is (or is not) available for use
DEFAULT (program)
DELUSER (program)
LOGOFF
LOGON
O[BEY]
PASSWORD (program)
PMSEARCH
RELOAD (program)
REMOTEPASSWORD
RPASSWRD (program)
SETPROMPT
SETTIME
SINK
SWITCH
SYSTEM
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
VOLUME
XBUSDOWN
XBUSUP
YBUSDOWN
YBUSUP
Table 7-8 lists the built-in functions and variables that support system environment
management.
Table 7-8. System Environment Management Built-In Functions and
Variables (page 1 of 2)
Function
Description
#ADDDSTTRANSITION
#BACKUPCPU
#BREAKMODE (variable)
#CHANGEUSER
#DEFAULTS (variable)
#DELAY
#INTERACTIVE
#LOGOFF
#MYGMOM
#MYSYSTEM
#MYTERM (variable)
#PMSEARCHLIST
(variable)
#PREFIX (variable)
#PROMPT (variable)
#REPLYPREFIX (variable)
#SETSYSTEMCLOCK
#SPIFORMATCLOSE
#SWITCH
#SYSTEM
#SYSTEMNAME
#SYSTEMNUMBER
#TACLOPERATION
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-12
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
M a na g ing th e T A C L E n viron m en t
Description
#TACLSECURITY
(variable)
#USERID
#USERNAME
#XLOGON
Description
ATTACHSEG
CREATESEG
DETACHSEG
HOME
LOAD
USE
Table 7-10 lists the built-in functions and variables that support the TACL environment.
Table 7-10. TACL Environment Commands
Function
Description
#ERRORNUMBERS
#GETPROCESSSTATE
#HOME
#LOAD
#SEGMENT
#SEGMENTCONVERT
#SEGMENTINFO
#SETPROCESSSTATE
#SETCONFIGURATION
#USELIST
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-13
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
For more information about other functions and commands that process text, see the
individual function and command descriptions in Section 8, UTILS:TACL Commands
and Functions and Section 9, Built-In Functions and Variables. In addition, the TACL
Programming Guide contains examples showing how to use these functions.
The commands in Table 7-11 provide data manipulation capabilities.
Table 7-11. Data Manipulation Commands (page 1 of 2)
Command
Description
_COMPAREV
COMPUTE
_CONTIME_TO_TEXT
_CONTIME_TO_TEXT_DATE
_CONTIME_TO_TEXT_TIME
COPYVAR
FILETOVAR
JOIN
KEEP
_LONGEST
_MONTH3
OUTVAR
POP
PUSH A
SET VARIABLE
VARTOFILE
VCHANGE
VCOPY
VDELETE
VFIND
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-14
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
VINSERT
VLIST
VMOVE
Table 7-12 summarizes the built-in functions and variables that manipulate text in
variables.
Table 7-12. Data Manipulation Built-In Functions and Variables (page 1 of 3)
Function
Description
#APPEND
#APPENDV
#ARGUMENT
#CHARACTERRULES
(variable)
#CHARADDR
#CHARBREAK
#CHARCOUNT
#CHARDEL
#CHARFIND
#CHARFINDR
#CHARFINDRV
#CHARFINDV
#CHARGET
#CHARGETV
#CHARINS
#CHARINSV
#COMPAREV
#COMPUTE
#COMPUTEJULIANDAYNO
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-15
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
#COMPUTETIMESTAMP
#COMPUTETRANSID
#CONTIME
#CONVERTPHANDLE
#CONVERTPROCESSTIME
#CONVERTTIMESTAMP
#DEF
Defines a variable
#DELTA
#EMPTY
#EMPTYV
#EXTRACT
#EXTRACTV
#FRAME
#GETSCAN
#INFORMAT (variable)
#INTERPRETJULIANDAYNO
#INTERPRETTIMESTAMP
#INTERPRETTRANSID
#JULIANTIMESTAMP
#KEEP
#LINEADDR
#LINEBREAK
#LINECOUNT
#LINEDEL
#LINEFIND
#LINEFINDR
#LINEFINDRV
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
Description
#LINEFINDV
#LINEGET
#LINEGETV
#LINEINS
#LINEINSV
#LINEJOIN
Description
#CASE
#ERRORTEXT
#EXCEPTION
#EXIT
#FILTER
#IF
#LOOP
#RAISE
#RETURN
#ROUTINENAME
#WAIT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-17
S u m m a ry of C o m m a n ds an d B u ilt-In F un ctio n s
D eb u gg in g T A C L S ta te m e n ts
Description
BREAK
DEBUG
_DEBUGGER
SET INSPECT
Table 7-15 lists built-in functions and variables that provide debugging support.
Table 7-15. Debugging Built-In Functions and Variables
Function
Description
#BREAKPOINT
#DEBUGPROCESS
#INSPECT
#TRACE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
7-18
8
UTILS:TACL Commands and
Functions
This section describes the TACL commands and functions that are located in the
:UTILS:TACL directory. These commands and functions are typically used for
interactive tasks. Each description contains:
Description
ACTIVATE Command
ALTPRI Command
ASSIGN Command
ATTACHSEG Command
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-1
U T IL S :T A C L C om m an d s a nd F u nctio ns
C o m m an ds a nd P rog ra m s
Description
BACKUPCPU Command
BREAK Command
BUILTINS Command
CLEAR Command
CLICVAL Program
COLUMNIZE Command
COMMENT Command
_COMPAREV Function
COMPUTE Command
_CONTIME_TO_TEXT Function
_CONTIME_TO_TEXT_DATE
Function
_CONTIME_TO_TEXT_TIME
Function
COPYDUMP Program
COPYVAR Command
CREATE Command
CREATESEG Command
DEBUG Command
DEBUGGER Function
DEFAULT Program
DETACHSEG Command
ENV Command
EXIT Command
FC Command
FILEINFO Command
FILENAMES Command
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-2
U T IL S :T A C L C om m an d s a nd F u nctio ns
C o m m an ds a nd P rog ra m s
Description
FILES Command
FILETOVAR Command
HELP Command
HISTORY Command
HOME Command
INITTERM Command
INLECHO Command
INLEOF Command
INLOUT Command
INLPREFIX Command
INLTO Command
IPUCOM Program
JOIN Command
KEEP Command
KEYS Command
LOAD Command
LOADEDFILES Command
LOGOFF Command
LOGON Command
_LONGEST Function
_MONTH3 Function
O[BEY] Command
OUTVAR Command
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-3
U T IL S :T A C L C om m an d s a nd F u nctio ns
C o m m an ds a nd P rog ra m s
Description
PARAM Command
PASSWORD Program
PAUSE Command
PMSEARCH Command
PMSG Command
POP Command
POSTDUMP Utility
PPD Command
PURGE Command
PUSH Command
REMOTEPASSWORD
Command and RPASSWRD
Program
RENAME Command
REMOTEPASSWORD
Command and RPASSWRD
Program
RUN[D|V] Command
SEGINFO Command
SEMSTAT Program
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-4
U T IL S :T A C L C om m an d s a nd F u nctio ns
R estricte d C om m a nd s
Description
SETPROMPT Command
SHOW Command
SINK Command
STATUS Command
STOP Command
SUSPEND Command
SWITCH Command
SYSTEM Command
SYSTIMES Command
TACL Program
TIME Command
USE Command
USERS Program
VARIABLES Command
VARINFO Command
VARTOFILE Command
VCHANGE Command
Restricted Commands
Only group managers (user ID n,255) can execute the commands in Table 8-2.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-5
U T IL S :T A C L C om m an d s a nd F u nctio ns
R estricte d C om m a nd s
Description
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-6
U T IL S :T A C L C om m an d s a nd F u nctio ns
:U T IL S :T A C L C o m m an d D e scription s
Only super-group users (user ID 255,n) can execute the commands in Table 8-3.
Table 8-3. Super-Group User Commands
Command or Function
Description
ADDDSTTRANSITION
Command (Super-Group Only)
RECEIVEDUMP Command
(Super-Group Only)
XBUSDOWN/YBUSDOWN
Command (Super-Group Only)
XBUSUP/YBUSUP Command
(Super-Group Only)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-7
U T IL S :T A C L C om m an d s a nd F u nctio ns
A C T IV A T E C o m m a n d
ACTIVATE Command
Use the ACTIVATE command to restart a process previously suspended by the
SUSPEND Command on page 8-217 or the #SUSPENDPROCESS Built-In Function
on page 9-394.
ACTIVATE [ [\node-name.]{$process-name | cpu,pin } ]
\node-name
is the system where the process resides.
$process-name
is the name of the process or process pair you want to restart.
cpu,pin
is the CPU number and process identification number for the process you want to
restart.
Considerations
If you omit the process specification, ACTIVATE restarts the last process TACL
started or for which TACL paused, if that process is still running. That process is
called the default process. You can use the #PROCESS Built-In Function on
page 9-290 to determine the name or CPU and PIN of the default process. If no
default process exists, you must include a process specification.
The super ID can activate any suspended process.
A group manager whose process accessor ID matches the user ID of any member
of the group can activate any suspended process owned by someone in the group.
(For a discussion of process accessor IDs, see the Guardian Users Guide. For
restrictions that apply to processes running on remote systems, see the Expand
Network Management and Troubleshooting Guide.)
Users other than super-group users and group managers can activate only those
processes with a process accessor ID that matches their own user ID.
A restarted process is placed in the queue of processes that are waiting for
execution. In the queue, the process with the highest priority is executed first, so a
newly activated process immediately begins execution only if it has the highest
execution priority. You can set execution priority with the ALTPRI Command on
page 8-20.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-8
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D D E F IN E C o m m a n d
Considerations
To modify the working attribute set before you create a DEFINE, use the SET
DEFINE command. To display the working attribute set or the attributes that are
currently set or defaulted, use the SHOW DEFINE command.
Attributes you set in an ADD DEFINE command (known as the ADD DEFINE
attribute set) do not become part of the working attribute set.
The ADD DEFINE command checks for consistency among the current attributes
(this includes attributes you set before entering the ADD DEFINE command, as
well as the ADD DEFINE attribute set). If the current attributes are incomplete or
inconsistent, an error occurs and no DEFINE is created. For example, if you enter
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-9
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D D E F IN E C o m m a n d
an ADD DEFINE command that does not make a complete attribute set (that is, if a
required attribute is still missing), TACL displays this message:
Current attribute set is incomplete
Because the CLASS attribute works like a subtype of DEFINE, CLASS affects the
ADD DEFINE command in these ways:
You cannot specify an attribute that is not valid for the CLASS of the DEFINE
you are adding. For example, when the default CLASS is in effect (CLASS
MAP), entering this command produces this error message:
79> ADD DEFINE =TAPE1, LABELS IBM
There is no attribute "LABELS" for the current class
When a backup TACL process takes over, TACL deletes existing DEFINEs.
To obtain error information, use the #ERRORNUMBERS Built-In Variable on
page 9-160.
Examples
1. Suppose that you are using a long file name in a series of commands or procedure
calls. Using a MAP DEFINE for file-name redirection, you can substitute a shorter
name for the long name. For example, this command sets up a MAP DEFINE (by
default) with the name =PLUTO:
80> ADD DEFINE =PLUTO, FILE \FAR.$OFF.WORLDS.PLUTO
Now you can use the name =PLUTO wherever you would have used the longer file
name, and the system knows that you mean \FAR.$OFF.WORLDS.PLUTO.
2. This command sets up a TAPE DEFINE named =S2 that describes a tape file on
the IBM standard labeled tape volume number 58. If you specify LABELS IBM, you
must also specify FILEID. Because the FILESEQ attribute defaults to 1, the file is
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-10
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D D E F IN E C o m m a n d
the first one on the tape. Data is to be translated from the ASCII format to EBCDIC.
The USE EXTEND attribute indicates that data is to be added to the end of the file.
81> ADD DEFINE =S2, CLASS TAPE, LABELS IBM, FILEID $TAPE,&
81> &VOLUME 58, EBCDIC OUT, USE EXTEND
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-11
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D D S T T R A N S IT IO N C o m m an d (S u p er-G ro u p
O nly)
Considerations
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D D S T T R A N S IT IO N C o m m an d (S u p er-G ro u p
O nly)
Example
To add two periods of daylight savings time (from April 1, 1986, to September 1, 1986,
and from April 1, 1986, to September 1, 1987), enter:
69> ADDDSTTRANSITION 01 APR 1986, 2:00 LST, 01 SEP 1986, &
69> &2:00 LST, 1:00
70> ADDDSTTRANSITION 01 SEP 1986, 2:00 LST, 01 APR 1987, &
70> &2:00 LST, 0:00
71> ADDDSTTRANSITION 01 APR 1987, 2:00 LST, 01 SEP 1987, &
71> &2:00 LST, 1:00
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-13
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D U S E R P ro gram (G ro up M a na ge rs O nly)
Considerations
Only a group manager or the super ID can add new users to a system. Group
managers can add new users to their respective groups; the super ID can add new
users to any group.
The super ID can create a new group by adding a new user with a previously
unused group-id and user-id.
A group does not need to have a group manager.
The logon defaults for a new user who was just added to the system are volume
$SYSTEM, subvolume NOSUBVOL, and disk file security AAAA.
Examples
1. Assume that there is no group name MANUF and no group ID 8 in the system. In
one ADDUSER command, the super ID can create a new group (MANUF) and add
a new user (STELLA) with group ID 8 and user ID 1:
12> ADDUSER MANUF.STELLA, 8,1
MANUF.STELLA (8,1) HAS BEEN ADDED TO THE USERID FILE.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-14
U T IL S :T A C L C om m an d s a nd F u nctio ns
A D D U S E R P ro gram (G ro up M a na ge rs O nly)
2. The super ID can also add a manager to the MANUF group by adding a user with
user ID 255 and group ID 8:
13> ADDUSER MANUF.HONCHO, 8,255
MANUF.HONCHO (8,255) HAS BEEN ADDED TO THE USERID FILE.
3. The new manager can now add other users to the group:
14> ADDUSER MANUF.MABEL, 8,2
MANUF.MABEL (8,2) HAS BEEN ADDED TO THE USERID FILE.
15> ADDUSER MANUF.FRED, 8,44
MANUF.FRED (8,44) HAS BEEN ADDED TO THE USERID FILE.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-15
U T IL S :T A C L C om m an d s a nd F u nctio ns
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-16
U T IL S :T A C L C om m an d s a nd F u nctio ns
A LT E R D E F IN E C o m m a n d
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-17
U T IL S :T A C L C om m an d s a nd F u nctio ns
A LT E R D E F IN E C o m m a n d
Considerations
An ALTER DEFINE command affects existing DEFINE statements only and does
not change the working attribute set. Similarly, an ALTER DEFINE command
affects DEFINEs for the current TACL process only; any DEFINE that was propagated from the current TACL to another process is unchanged.
Because the CLASS attribute establishes new attributes for a DEFINE, you should
keep these points in mind when you use the ALTER DEFINE command:
Attributes are altered in the order in which they are specified in the ALTER
DEFINE command.
If you include the CLASS attribute, all new attributes are established for the
DEFINE; any existing attributes are erased (including any attributes preceding
CLASS in the ALTER command itself). The new attributes are those
associated with the specified CLASS, and each attribute has its initial setting.
You cannot alter an attribute that is not valid for the class of that DEFINE. For
example, if =DFILE is CLASS TAPE, this command produces this error:
32> ALTER DEFINE =DFILE, FILE $MUNCH.NUMBERS.DIGIT
There is no attribute "FILE" for the current class
Before a DEFINE is altered, the ALTER DEFINE command checks for consistency
among the new attribute values specified and the other existing attributes of the
DEFINE. If the attributes are incomplete or inconsistent, an error occurs and no
changes are made to the DEFINE.
When a backup TACL process takes over, TACL deletes existing DEFINEs.
To obtain error information, use the #ERRORNUMBERS Built-In Variable on
page 9-160.
Example
This ALTER DEFINE command changes the DEVICE attribute in the DEFINEs named
=ONE and =TWO so that when the DEFINE is opened, the tape process searches for
the tape files MAYRCDS and JUNRCDS on the tape mounted on tape drive $TAPE1:
27> INFO DEFINE (=ONE, =TWO), DETAIL
DEFINE NAME=ONE
CLASS TAPEVOLUME 4335
LABELS ANSI
FILEID MAYRCDS
DEVICE $TAPE
DEFINE NAME =TWO
CLASS TAPE
VOLUME 4335
LABELS ANSI
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-18
U T IL S :T A C L C om m an d s a nd F u nctio ns
A LT E R D E F IN E C o m m a n d
FILEID JUNRCDS
DEVICE $TAPE
28> ALTER DEFINE ( =ONE, =TWO ), DEVICE $TAPE1
29> INFO DEFINE (=ONE, =TWO), DETAIL
DEFINE NAME =ONE
CLASS TAPE
VOLUME 4335
LABELS ANSI
FILEID MAYRCDS
DEVICE $TAPE1
DEFINE NAME =TWO
CLASS TAPE
VOLUME 4335
LABELS ANSI
FILEID JUNRCDS
DEVICE $TAPE1
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-19
U T IL S :T A C L C om m an d s a nd F u nctio ns
ALTPRI Command
Use the ALTPRI command to change the execution priority of a process or process
pair.
ALTPRI [\node-name.]{$process-name | cpu,pin } , pri
\node-name
is the system where the process resides.
$process-name
is the name of the process or process pair.
cpu,pin
is the CPU number and process identification number for the process.
pri
is the new execution priority of the process. It is an integer in the range from 1
through 199 (1 is lowest priority).
Considerations
If you do not specify a process, ALTPRI changes the priority of the default process.
The default process is the process that was last started by the current TACL or for
which TACL most recently paused, if that process still exists. To determine the default
process, use the #PROCESS Built-In Function on page 9-290.
The super ID can change the priority of any process in the system.
A group manager can alter the priority of any process whose process accessor ID
matches any user ID in the group.
Users other than group managers can change the priority of only those processes
whose process accessor IDs match their user ID. (For a description of process
accessor IDs and creator accessor IDs, see the Guardian Users Guide.)
Before increasing the priority of a process, carefully consider the effect the change
might have on system performance. For example, assigning a high priority to
processes with a large amount of CPU activity, such as those involving lengthy
arithmetic computations, can significantly degrade system performance.
Example
Assume that a process named $SLOW is currently running with an execution priority of
110. You can raise the execution priority of $SLOW to 140 by entering:
12> ALTPRI $SLOW, 140
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-20
U T IL S :T A C L C om m an d s a nd F u nctio ns
A S S IG N C o m m a n d
ASSIGN Command
Use the ASSIGN command to assign names of actual files to logical file names used in
programs (such as those written in COBOL, FORTRAN, and other programming
languages) and, optionally, to specify the characteristics of such files. If you omit the
parameters of the ASSIGN command, ASSIGN displays the assigned values for all
assignments currently in effect.
ASSIGN [ logical-unit [ , [ actual-file-name ]
[ , create-open-spec ] ... ] ]
logical-unit
is the name to which a file name or file attributes are assigned. For logicalunit, specify one of these:
*. logical-file
program-unit.logical-file
logical-file
Both program-unit and logical-file names consist of 1 to 31 alphanumeric,
hyphen (-), or circumflex (^) characters.
The exact meanings of program-unit, the asterisk (*), and logical-file depend on the
application; in general:
program-unit is the name used in the source program to which the file-name
assignment is to apply.
* applies the assignment to all program units in the object program file being run.
logical-file is the name of the file as given in the source program.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-21
U T IL S :T A C L C om m an d s a nd F u nctio ns
A S S IG N C o m m a n d
extent-spec
exclusion-spec
access-spec
CODE file-code
REC record-size
BLOCK block-size
extent-spec
is the size of the file extents allocated to the file. Specify either of these:
EXT [ ( ] pri-extent-size [ )
EXT ( [ pri-extent-size ] , sec-extent-size )
pri-extent-size
is the size of the primary file extent to be allocated to the file. It is an
integer in the range from 1 through 65535. (For treatment of priextent-size by applications written in other languages, see the
appropriate language manual.)
sec-extent-size
is the size of the secondary extents, allocated to the file after the primary
extent is allocated. It is an integer in the range from 1 through 65535. (For
details on treatment of sec-extent-size by applications written in other
languages, see the appropriate language manual.)
exclusion-spec
is the exclusion mode for logical-unit. It determines the circumstances under
which other processes can access the file. Specify exclusion-spec as one
of these:
EXCLUSIVE
SHARED
PROTECTED
EXCLUSIVE
means that no other processes can access actual-file-name while the
program that refers to logical-unit has the file open.
SHARED
means that other processes can both read and write to actual-filename while the program that refers to logical-unit has the file open.
PROTECTED
means that another process can read, but not write to, actual-filename while the program that refers to logical-unit has the file open.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-22
U T IL S :T A C L C om m an d s a nd F u nctio ns
A S S IG N C o m m a n d
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-23
U T IL S :T A C L C om m an d s a nd F u nctio ns
A S S IG N C o m m a n d
Considerations
Examples
1. You can assign an actual file name and file-creation attributes to the logical file
PRTFILE used by a COBOL program by entering:
14> ASSIGN prtfile, myfile, EXT 4096, CODE 9999,&
14> &EXCLUSIVE, OUTPUT
2. You can assign an actual file name and file-creation attributes to the logical file
FT002 used by a FORTRAN program by entering:
15> ASSIGN FT002, datafile, INPUT, EXCLUSIVE
3. You can get a list of the attributes of the logical file PRTFILE by entering:
16> ASSIGN prtfile
Here is an example of the information displayed:
PRTFILE
Physical file:
Primary extent:
File code:
MYFILE
4096
9999
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-24
U T IL S :T A C L C om m an d s a nd F u nctio ns
Exclusion:
Access:
A S S IG N C o m m a n d
EXCLUSIVE
OUTPUT
4. You can list the assigned attributes of all logical files by entering:
17> ASSIGN
Here is an example of the information displayed:
PRTFILE
Physical file:
Primary extent:
File code:
Exclusion:
Access:
MYFILE
4096
9999
EXCLUSIVE
OUTPUT
Physical file:
Exclusion:
Access:
DATAFILE
EXCLUSIVE
INPUT
FT002
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-25
U T IL S :T A C L C om m an d s a nd F u nctio ns
ATTACHSEG Command
Use the ATTACHSEG command to load an existing TACL segment file into memory
and associate it with a directory so that TACL can gain quick access to its variables.
ATTACHSEG {PRIVATE | SHARED} file-name directory-name
PRIVATE
specifies that the segment is to be opened for use by only one process (yours) and
that data can be written into it.
SHARED
specifies that the segment is to be opened in the read-only mode and that other
processes can open the segment for reading only.
file-name
is the name of a TACL segment file, created previously by a CREATESEG
command.
directory-name
is the name of a variable that is to be pushed and set to a directory of the variables
in the segment file.
Considerations
You must have both read and write access to the segment file.
The segment file remains open and unchanged until you issue a DETACHSEG
command for it. If for any reason TACL stops while updating the file during the
DETACHSEG operation, the file contents are unpredictable, and any future
attempts to attach the file will fail.
There is a delay while TACL reads the segment file. A segment file typically
contains unused space; TACL reads only the valid data within the file, not the
entire file.
If access is SHARED, you must have at least read access to the segment file.
To display a table of information about all the segment files in use by your TACL
process, use the SEGINFO Command on page 8-168.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-26
U T IL S :T A C L C om m an d s a nd F u nctio ns
For more information about segment files, see the CREATESEG Command on
page 8-46.
Note. The PRIVATE option allows access by only one process. You cannot access a segment
file if you have opened it with PRIVATE access with another TACL process.
Examples
This command loads the segment file MYSEGFIL into memory and records the names
of the loaded variables in the directory MYDIR. Other users can access the segment
as well.
23> ATTACHSEG SHARED mysegfil :mydir
These commands attach two segment files to a directory. The second file is attached
through a subdirectory:
23>ATTACHSEG PRIVATE myseg :mydir
24>ATTACHSEG SHARED yourseg :mydir:subdir
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-27
U T IL S :T A C L C om m an d s a nd F u nctio ns
BACKUPCPU Command
Use the BACKUPCPU command to start a backup process for the current TACL
process or to replace an existing backup process. The BACKUPCPU command is an
alias for the #BACKUPCPU built-in function.
BACKUPCPU [ cpu ]
cpu
is the number of the processor where the backup TACL process is to be started.
Specify cpu as an integer in the range from 0 through 15. If you omit cpu,
BACKUPCPU deletes the existing backup process.
Considerations
BACKUPCPU with no cpu specification has no effect if the current TACL process
has no backup.
Only a named TACL process can have a backup. (For more information on named
processes, see the NAME option in the description of the RUN[D|V] Command on
page 8-156.)
The backup CPU cannot be the same as the primary CPU.
The named CPU need not be running at the time that BACKUPCPU is issued.
If you specify a backup CPU and a backup process already exists, TACL displays
an error message.
If the primary CPU becomes unavailable, TACL switches to the backup CPU. After
the primary CPU is reloaded, TACL switches back to the primary CPU. If a user is
logged on, TACL postpones this switch till the user logs off.
You can force your TACL to switch to the backup CPU by using the SWITCH
command.
All events, such as a backup-create error or an I/O error event, and the event
details are logged to the primary or $0 collector. This format is used:
TACL BACKUP CREATE ERROR: error, DETAIL: error-detail
error
is the error number returned by PROCESS_CREATE.
error-detail
is the error detail value returned by PROCESS_CREATE.
For more information about the $0 collector, see the EMS Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-28
U T IL S :T A C L C om m an d s a nd F u nctio ns
When a backup TACL process takes over, an initial logon state is established. All
variables, ASSIGNs, PARAMs, and DEFINEs are reset, and the TACLLOCL file
and your TACLCSTM file are invoked. The history buffer index is set to 1.
If an error occurs while TACL is trying to create the backup process or if the
backup CPU is down, TACL waits 3 minutes before trying to create the backup.
Examples
1. Suppose that you are running a TACL process named $CMT1 (the name displayed
by the WHO and PPD commands). When you enter the STATUS *, TERM
command, you see that $CMT1 does not have a backup process:
$E197 10,122 150 001 8,1 $SYSTEM.SYSTEM.TACL $FURD
You start a backup TACL process in CPU 11 by entering:
12> BACKUPCPU 11
TACL displays this response after creating the backup process:
BACKUP PROCESS CREATED IN CPU 11
Entering STATUS *, TERM now displays this information:
$E197 10,122 150 001 8,1 $SYSTEM.SYSTEM.TACL $FURD
$E197 B 11,122 150 R 000 8,1 $SYSTEM.SYSTEM.TACL $FURD
This display shows that the primary TACL process (running in processor 10, with
process number 122) now has a backup TACL process (running in processor 11,
with process number 122). Both the primary and backup processes have a priority
of 150. See the STATUS Command on page 8-206 for explanations of the other
categories in the STATUS display.
2. To delete this newly created backup process, enter:
14> BACKUPCPU
15>
which TACL acknowledges with:
STOPPED: 11,122
BACKUP PROCESS DELETED
3. To move your backup process from one CPU to another, enter:
15>BACKUPCPU
STOPPED: 11,111
BACKUP PROCESS DELETED
16>BACKUPCPU 12
BACKUP PROCESS CREATED IN CPU 12
17>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-29
U T IL S :T A C L C om m an d s a nd F u nctio ns
BREAK Command
Use the BREAK command to set a debugging breakpoint on a specified variable level.
BREAK [ variable-level ]
variable-level
is the name of an existing variable level or built-in variable.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-30
U T IL S :T A C L C om m an d s a nd F u nctio ns
B U IL T IN S C o m m a n d
BUILTINS Command
Use the BUILTINS command to display the names of the TACL built-in functions, builtin variables, or both.
BUILTINS [ / {
FUNCTIONS | VARIABLES } / ]
FUNCTIONS
displays a list of the built-in functions.
VARIABLES
displays a list of the built-in variables.
Considerations
If you specify neither FUNCTIONS nor VARIABLES, TACL displays all built-in functions
and variables.
To obtain the list of built-in functions and variables from within a TACL macro or
routine, use the #BUILTINS Built-In Function on page 9-38.
Example
This example illustrates the use of the BUILTINS command:
3> BUILTINS / VARIABLES /
The built in variables are:
#ASSIGN
#BREAKMODE
#CHARACTERRULES
#DEFAULTS
#DEFINEMODE
#ERRORNUMBERS
#EXIT
#HELPKEY
#HOME
#IN
#INFORMAT
#INLINEECHO
#INLINEOUT
#INLINEPREFIX
#INLINEPROCESS
#INLINETO
#INPUTEOF
#INSPECT
#MYTERM
#OUT
#OUTFORMAT
#PARAM
#PMSEARCHLIST
#PMSG
#PREFIX
#PROCESSFILESECURITY
#PROMPT
#REPLYPREFIX
#SHIFTDEFAULT
#TACLSECURITY
#TRACE
#USELIST
#WAKEUP
#WIDTH
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-31
U T IL S :T A C L C om m an d s a nd F u nctio ns
Examples
1. A super-group user in a four-processor system can bring down the X bus from
processor 1 to all other processors by entering:
14>
THE
THE
THE
THE
BUSCMD X, DOWN, 1, -1
X BUS FROM CPU 01 TO 00
X BUS FROM CPU 01 TO 01
X BUS FROM CPU 01 TO 02
X BUS FROM CPU 01 TO 03
HAS
HAS
HAS
HAS
BEEN
BEEN
BEEN
BEEN
DOWNED.
DOWNED.
DOWNED.
DOWNED.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-32
U T IL S :T A C L C om m an d s a nd F u nctio ns
CLEAR Command
Use the CLEAR command to delete logical-file assignments made with the ASSIGN
command or parameters set with the PARAM command.
CLEAR { ALL } | { ALL ASSIGN |
ALL PARAM |
ASSIGN logical-unit |
PARAM param-name }
ALL
deletes all logical-file assignments and parameters.
ALL ASSIGN
deletes all logical-file assignments made with the ASSIGN command.
ALL PARAM
deletes all parameters set with the PARAM command.
ASSIGN logical-unit
deletes the assignment for logical-unit; see the ASSIGN Command on
page 8-21 for information about logical-unit.
PARAM param-name
deletes param-name; see the PARAM Command on page 8-113 for information
about param-name.
Examples
1. This command deletes all logical-file assignments made with the ASSIGN
command and all parameters set with the PARAM command:
14> CLEAR ALL
2. To delete all logical-file assignments made with the ASSIGN command, enter:
15> CLEAR ALL ASSIGN
3. You can delete the assignment for the logical file PRNTFILE and the information
associated with it by entering:
16> CLEAR ASSIGN prntfile
4. You can delete the parameter SWITCH-1 and its value by entering:
17> CLEAR PARAM switch-1
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-33
U T IL S :T A C L C om m an d s a nd F u nctio ns
C L IC V A L P ro gram
CLICVAL Program
Use the CLICVAL program to validate a Core License file.
CLICVAL [-help | help ]
-help or help
displays CLICVAL help text.
CLICVAL validates whether the Core License file is located in the correct location for
use by the operating system and is valid for the system. CLICVAL also displays the
name of the file that was validated along with the validation results such as OK,
Missing, Corrupt, Invalid, Serial Number mismatch, and so on. The CLICVAL program
displays the contents of the license file, wherever possible, including the license file
version number, the system serial number, and the enabled number of IPUs and
CPUs. The contents cannot be displayed if the file is missing or corrupt.
You can use the CLICVAL program on RVUs prior to J06.13, to validate the Core
License file prior to upgrading to J06.13 or later from a prior RVU. If you are on J06.13
or a later RVU, you can use the OSM Service Connection action "Read Core License"
to validate the Core License file instead. See the Read Core License action online
help for more information.
For more information about when to use the CLICVAL tool to validate the core license
file, see the NonStop BladeSystem Planning Guide.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-34
U T IL S :T A C L C om m an d s a nd F u nctio ns
C O L U M N IZ E C o m m a n d
COLUMNIZE Command
Use the COLUMNIZE command to read a list of elements and display those elements
in one or more columns, taking into consideration the widest element in the list and the
value of the #WIDTH Built-In Variable on page 9-419.
COLUMNIZE list
list
is a list of elements separated by spaces.
Example
This example has an effect similar to that of the BUILTINS /VARIABLES/ command,
displaying a columnar list of TACL built-in variables.
10>COLUMNIZE [#SHIFTSTRING [#BUILTINS /VARIABLES/] ]
#ASSIGN
#BREAKMODE
#CHARACTERRULES
#DEFAULTS
#DEFINEMODE
#ERRORNUMBERS
#EXIT
#HELPKEY
#HOME
...
TACL adjusts the display to fit the OUT file width. To view the preceding built-in
variables in two columns, set the OUT file width to 60:
10>#SET #WIDTH 60
11>COLUMNIZE [#SHIFTSTRING [#BUILTINS /VARIABLES/] ]
#ASSIGN
#BREAKMODE
#CHARACTERRULES
#DEFAULTS
#DEFINEMODE
#ERRORNUMBERS
#EXIT
#HELPKEY
#HOME
...
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-35
U T IL S :T A C L C om m an d s a nd F u nctio ns
CO M M EN T Com m and
COMMENT Command
The COMMENT command causes TACL to ignore the rest of the command line.
COMMENT [ comment-text ]
comment-text
is any descriptive text you wish to include.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-36
U T IL S :T A C L C om m an d s a nd F u nctio ns
_ C O M P A R E V F u nctio n
_COMPAREV Function
Use the _COMPAREV function to compare one string with another. The _COMPAREV
function is an alias for the #COMPAREV built-in function.
_COMPAREV string-1 string-2
string-1 and string-2
are the names of existing variable levels or STRUCT items, text enclosed in
quotation marks, or a concatenation of such elements. The concatenation operator
is '+' (the apostrophes are required). Variables must not be of type DIRECTORY.
Result
_COMPAREV returns a nonzero value if the contents of the strings are the same, zero
if they are different.
Considerations
You can compare any combination of STRUCTs and STRUCT items with each
other. Such comparisons are case-sensitive.
You can compare any combination of variables that are not of type DIRECTORY or
STRUCT and are not STRUCT items. Such comparisons are not case-sensitive.
You should use _COMPAREV when a variable level contains text with spaces or
when you do not want to obtain the contents of a variable level.
The comparison is not case-sensitive; that is, an uppercase character is equivalent
to its lowercase counterpart.
To compare a text string to a template, use the #MATCH built-in function.
Examples
1. This example illustrates _COMPAREV, using #OUTPUT to display the result:
5>
6>
7>
8>
0
PUSH A B
#SET A Hello
#SET B Goodbye
#OUTPUT [_COMPAREV A B]
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-37
U T IL S :T A C L C om m an d s a nd F u nctio ns
CO M PU TE Com m and
COMPUTE Command
Use the COMPUTE command to display the value of an expression.
COMPUTE expression
expression
is an expression containing integer or string values and one or more operators, as
defined in Expressions on page 3-1.
Considerations
To obtain the value of an expression from within a TACL macro or routine, use the
#COMPUTE Built-In Function on page 9-71; it returns the result of the specified
arithmetic expression.
COMPUTE displays the calculation and its arithmetic result. Comparisons and
logical operators display -1 if the test is true, 0 if the test is false.
Because COMPUTE performs integer division, the fraction portion of the result is
omitted, as in 3/4 = 0.
Examples
1. This example illustrates simple use of the COMPUTE command:
6> COMPUTE 6 + 4
6 + 4 = 10
2. Equations are evaluated from left to right as indicated by the precedence for
operators. To change the order of evaluation, use parentheses:
7> COMPUTE 4 + 5 * 3
4 + 5 * 3 = 19
8> COMPUTE (4 + 5) * 3
(4 + 5) * 3 = 27
3. This example shows computations involving relational and logical expressions:
9> #PUSH oui,non
10> #SETMANY oui non, 1 0
11> COMPUTE oui < non
oui < non = 0
12> COMPUTE (non OR oui) AND NOT non
(non OR oui) AND NOT non = -1
4. This example illustrates string computations:
13> #PUSH a b
14> #SET a 1
15> #SET b 01
16> COMPUTE a=b
a=b = -1
17> COMPUTE a '=' b
a '=' b = 0
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-38
U T IL S :T A C L C om m an d s a nd F u nctio ns
_C O N T IM E _T O _T E X T F u nctio n
_CONTIME_TO_TEXT Function
Use the _CONTIME_TO_TEXT function to convert a numeric date and time to a
textual date and time.
_CONTIME_TO_TEXT contime-list
contime-list
is the date and time represented as seven numbers in this format:
yyyy mm dd hh mm ss hh
Result
_CONTIME_TO_TEXT returns the textual date and time representation of the sevennumber date and time returned by the #CONTIME Built-In Function on page 9-75.
Example
This example outputs the date and time in a textual format:
14> PUSH var
15> SET VARIABLE var [#CONTIME [#TIMESTAMP] ]
16> #OUTPUT [_CONTIME_TO_TEXT [var] ]
November 21, 1992 14:35:20
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-39
U T IL S :T A C L C om m an d s a nd F u nctio ns
_ C O N T IM E _T O _T E X T _ D A T E F u nctio n
_CONTIME_TO_TEXT_DATE Function
Use the _CONTIME_TO_TEXT_DATE function to convert a numeric date and time to a
textual date.
_CONTIME_TO_TEXT_DATE contime-list
contime-list
is the date and time represented as seven numbers in this format:
yyyy mm dd hh mm ss hh
Result
_CONTIME_TO_TEXT_DATE returns the textual representation of the date portion of
the seven-number date and time representation returned by the #CONTIME Built-In
Function on page 9-75.
Example
This example outputs the date in a textual format:
14> PUSH var
15> SET VARIABLE var [#CONTIME [#TIMESTAMP] ]
16> #OUTPUT [_CONTIME_TO_TEXT_DATE [var] ]
November 21, 1990
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-40
U T IL S :T A C L C om m an d s a nd F u nctio ns
_ C O N T IM E _ T O _ T E X T _ T IM E F u nctio n
_CONTIME_TO_TEXT_TIME Function
Use the _CONTIME_TO_TEXT_TIME function to convert a numeric date and time to a
textual time.
_CONTIME_TO_TEXT_TIME contime-list
contime-list
is the date and time represented as seven numbers in this format:
yyyy mm dd hh mm ss hh
Result
_CONTIME_TO_TEXT_TIME returns the textual representation of the time portion of
the seven-number date and time representation returned by the #CONTIME Built-In
Function on page 9-75.
Example
This example outputs the time in a textual format:
14> PUSH var
15> SET VARIABLE var [#CONTIME [#TIMESTAMP] ]
16> #OUTPUT [_CONTIME_TO_TEXT_TIME [var] ]
14:35:20
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-41
U T IL S :T A C L C om m an d s a nd F u nctio ns
C O P Y D U M P P ro gram
COPYDUMP Program
Use the COPYDUMP program to copy a tape dump onto a disk file or to compress an
existing disk dump file that is not compressed.
COPYDUMP [ / run-option [ , run-option ] ... / ]
source-file , dest-file
run-option
is any of the options described for the RUN[D|V] Command on page 8-156.
source-file
specifies the dump file that is to be copied and compressed. Specify either the
name of the tape device where the tape dump file is located or the name of a disk
dump file you want to copy.
If source-file is a disk file, it must be created by using the RCVDUMP program
or the RECEIVEDUMP TACL command. If source-file is a tape file, it must be
created by performing a tape dump.
dest-file
specifies the destination file of the COPYDUMP operation. Specify the name of a
disk file. If this disk file does not exist, it is created during the COPYDUMP
operation. If this disk file does exist, it must be empty (0 EOF) and have file code
9614.
Considerations
COPYDUMP is not supported on H-series systems.
You can also use FUP (CREATE and COPY) to copy tape dump files to disk files. But
COPYDUMP is faster, and generates a smaller disk dump file because it compresses
the dump. Also, COPYDUMP automatically determines the size of the disk dump file,
whereas you must specify the extent size of the disk file if you use FUP. The
COPYDUMP program usually resides in the file $SYSTEM.SYSnn.COPYDUMP.
Examples
If a tape dump file resides on the tape mounted on the tape drive $TAPE2, you can
copy and compress the tape dump file into the disk file $DATA.DUMPS.CPU1 with the
command:
47> COPYDUMP $TAPE2, $DATA.DUMPS.CPU1
To compress the disk dump file $BAS10.DUMPS.CPU3 into the disk file
$BAS10.CDUMPS.CPU3, enter:
48> COPYDUMP $BAS10.DUMPS.CPU3 , $BAS10.CDUMPS.CPU3
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-42
U T IL S :T A C L C om m an d s a nd F u nctio ns
COPYVAR Command
Use the COPYVAR command to copy the contents of one variable level to another.
COPYVAR variable-level-in variable-level-out
variable-level-in
is the name of an existing variable level.
variable-level-out
is the name of a variable level. COPYVAR performs an implicit PUSH command to
create a variable-level-out with the same data type as variable-level-in, regardless
of whether variable-level-out already exists.
Result
The COPYVAR command pushes variable-level-out and copies the contents of
variable-level-in to variable-level-out.
Example
This example copies the contents of the variable FIRSTDAY to the variable TEMPDAY.
14> OUTVAR firstday
FRIDAY
15> COPYVAR firstday tempday
16> OUTVAR tempday
FRIDAY
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-43
U T IL S :T A C L C om m an d s a nd F u nctio ns
CREATE Command
Use the CREATE command to create an unstructured disk file. An unstructured disk
file can contain a data-record structure that the file system does not recognize, or it can
be made up of an array of bytes without data-record structure.
CREATE file-name [ , parameter [ , parameter ] ]
file-name
is the name of the file to be created. If no volume or subvolume is specified in
file-name, the current volume name and subvolume name in effect for the TACL
process at the time of the request are used.
parameter
can be any of these:
extent-size
is the size of the file extents that can be allocated to the file. Specify extent-size
as an integer in the range 1 to 65535 for the number of 2048-byte data pages
in each extent. The disk process can allocate up to 16 extents (if the
MAXEXTENTS file attribute has not been altered from its default of 16) to any
file you create with the CREATE command. The default value for extentsize is 2.
PHYSICALVOLUME physical-volume
is the physical volume on which the logical file-name is to be created. If no
physical volume is specified in file-name, the default volume name in effect
for the TACL process at the time of the request is used.
If a logical volume is specified in file-name, the physical volume on which
the file is created is chosen by the system. The physical-volume parameter
overrides this selection
The PHYSICALVOLUME option should be used only if no physical volume is
specified in file-name. Otherwise, a file-system error is returned.
Considerations
The security of the file you create is the current default security at the time you
enter the command. See the DEFAULT Program on page 8-53 and VOLUME
Command on page 8-256 for information about changing default security.
You can change the security of a file with the FUP SECURE command. See the
File Utility Program (FUP) Reference Manual for a description of FUP SECURE.
FUP also has a CREATE command. When you create a file using the CREATE
command in TACL, the size of the first extent allocated (the primary extent) defines
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-44
U T IL S :T A C L C om m an d s a nd F u nctio ns
the size of all extents that are subsequently allocated (secondary extents). With the
FUP CREATE command, however, you can specify different sizes for primary and
secondary extents and can partition files into more than one volume. You can also
create files of a type other than unstructured. See the File Utility Program (FUP)
Reference Manual for a description of the FUP CREATE command.
Examples
1. To create an unstructured disk file named DATAFL in your current default
subvolume, enter:
14> CREATE datafl
Because the default extent size is two pages (4096 bytes), the largest size
DATAFL can attain (when the maximum of 16 extents is allocated to the file) is 32
pages.
2. To create an unstructured file named BANANA in the subvolume $DSK1.SVOL,
with an extent size of 10,240 bytes (5 pages), enter:
15> CREATE $dsk1.svol.banana, 5
The largest size BANANA can attain (when the maximum of 16 extents is allocated
to the file) is 80 pages.
3. To specify a physical volume name when creating a logical file, enter:
>3 CREATE $v.s.f,2,$mg or CREATE $v.s.f,$mg,2
Either syntax specifies that logical file $v.s.f be created with a two-page extent
size on physical volume $mg.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-45
U T IL S :T A C L C om m an d s a nd F u nctio ns
CREATESEG Command
Use the CREATESEG command to create a TACL segment file.
CREATESEG file-name
file-name
is the name to be assigned to the created segment file.
Considerations
Set the #USELIST built-in variable to gain access to the segment file.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-46
U T IL S :T A C L C om m an d s a nd F u nctio ns
Examples
1. This command creates a TACL segment file (file code 440) named MYSEG.
8> CREATESEG myseg
9>
2. These commands create a segment file called MYSEGFIL, attach the segment file
to a directory called :mydir, load a set of routines from a file called
$DATA.TACL.ROUTINES, detach the segment from private use (and complete the
transfer of data to the segment file), and attach the segment for shared use:
8>CREATESEG mysegfil
9>ATTACHSEG PRIVATE mysegfil :mydir
10>HOME :mydir
11>LOAD /KEEP 1/ $DATA.TACL.ROUTINES
12>HOME
13>DETACHSEG :mydir
14>ATTACHSEG SHARED mysegfil :mydir
15>#SET #USELIST [#USELIST] :mydir
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-47
U T IL S :T A C L C om m an d s a nd F u nctio ns
DEBUG Command
Use the DEBUG command to initiate debugging for a process that is already running.
Entering the DEBUG command is one way to invoke the Debug program or the Inspect
debugger.
If you do not specify a process ($process-name or cpu,pin), the Debug and Inspect
programs begin debugging the process most recently started by TACL, if that process
is still in existence.
For information on the Debug program, see the Debug Manual. For information about
the Inspect symbolic debugger, see the Inspect Manual.
The program DEBUG is not available for use on systems running H-series software.
See the Considerations section on page 8-49 for more details.
Considerations
You can enter the DEBUG command interactively only, not in an input file or an
OBEY file.
Unless you are a group manager or the super ID, you can debug only those
processes with process accessor IDs that match your user ID. You must also have
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-48
U T IL S :T A C L C om m an d s a nd F u nctio ns
read access to the program file. (For a description of process accessor IDs, see
the Guardian Users Guide.)
A group manager can debug any process whose process accessor ID matches the
user ID of any user in the group. The manager must also have read access to the
program file.
The super ID can debug any process. Only the super ID can debug privileged
processes.
The process you name in the DEBUG command does not enter the debug mode
until it executes its next instruction in the user code space. The process cannot
enter the debug state while executing system code.
DEBUG is the default debugger. When you enter the DEBUG command, DEBUG
is invoked unless INSPECT was designated as the debugger for the process when
the process was created. You can designate INSPECT as the default debugger in
any of these ways:
H-Series Usage
The program DEBUG is not available for use on systems running H-series software.
The DEBUG command invokes a debugger, it can be Inspect, Native Inspect
(eInspect, which is not in the family of Inspect debuggers), or Visual Inspect.
The rules about which debugger gets invoked are approximately the same as for the
RUND command. That is, if the INSPECT attribute is set ON anywhere (in the object
file during compilation, or on the TACL command line using the SET command), you
will get a debugger in the Inspect family (either Inspect or VI), unless of course neither
of these debuggers is available, and then you get the default debugger, eInspect. If
the Inspect attribute is OFF, you get Native Inspect (eInspect).
Inspect is invoked only for TNS accelerated/interpreted programs (never for TNS/E
native programs), while Visual Inspect can handle both of these. Native Inspect
handles only TNS/E native programs and snapshots.
Examples
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-49
U T IL S :T A C L C om m an d s a nd F u nctio ns
To use the terminal $WHITE to debug the process whose process ID is 8,45, enter:
15> DEBUG 8,45, TERM $WHITE
A DEBUG or INSPECT prompt then appears on terminal $WHITE.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-50
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E B U G G E R F u nctio n
DEBUGGER Function
If tracing is enabled (see #TRACE Built-In Variable on page 9-406), the TACL trace
facility displays the next line to be executed, then immediately invokes the
_DEBUGGER function before executing that code. You can set breakpoints, modify
variables, and invoke TACL commands while debugging.
For an example of _DEBUGGER function use, see the TACL Programming Guide.
_DEBUGGER current-trace-value reason-for-entry
current-trace-value
is the value of #TRACE, which always equals -1 (true) when invoked by TACL.
reason-for-entry
is TRACE or BREAK.
Considerations
When #TRACE is not zero, TACL calls _DEBUGGER immediately after displaying
the code that is next to be invoked. In this case, current-trace-value is always -1
and reason-for-entry is always TRACE.
It is possible to replace _DEBUGGER with a debugging function of your own
devising.
If TACL is about to invoke a variable on which you have set a breakpoint, TACL
invokes _DEBUGGER. _DEBUGGER prompts with - num- (the current history
number). At this point you can enter a command. If it is a TACL command, it is
passed on to TACL for execution. If it is a _DEBUGGER command, _DEBUGGER
executes it. The _DEBUGGER commands are:
B[REAK] [ variable-level ]
sets an invocation breakpoint on a variable level. If you omit variablelevel, the command displays all breakpoints currently set.
C[LEAR] { variable-level | * }
clears the invocation breakpoint for the specified variable-level. If you use
the asterisk (*), the command clears all breakpoints.
D[ISPLAY] variable-level
displays the contents of the specified variable level.
M[ODIFY] variable-level
allows you to modify the contents of the specified variable level.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-51
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E B U G G E R F u nctio n
R[ESUME]
exits the debugger and continues execution of TACL statements.
ST[EP]
invokes the next function, then waits for you to press RETURN before
performing the next action. You can continue in this way, stepping through the
function.
You can abbreviate each of these commands to the letter or letters outside the
square brackets; that is, you can issue DISPLAY as D or STEP as ST.
Caution. While TACL is in the debugging mode, you can issue any TACL commands that do
not conflict with _DEBUGGER commands. Use extreme care in issuing any commands that
would affect _DEBUGGER or its environment, including altering a variable level that is being
traced. It is unwise to include an #UNFRAME, for instance, because the _DEBUGGER
environment would be destroyed
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-52
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E F A U LT P ro gram
DEFAULT Program
Use the DEFAULT program to set your logon (saved) default system, volume, and
subvolume names, and to set your logon disk file security. The logon defaults are in
effect whenever you log on.
DEFAULT [ / run-option [ , run-option ] ... / ] default-names
["default-security"] "default-security"
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
default-names
are the volume and subvolume names that are to be your logon defaults; that is,
these are the current defaults when you log on or enter the VOLUME command
without any parameters. You can also specify a logon default node name. TACL
uses the current default node, volume, and subvolume names to expand partial file
names.
The form of default-name is:
[\node-name.] volume-or-subvolume-names
\node-name
is the node name that is to be your default when you log on or enter the
SYSTEM command without parameters. If you omit node-name, your logon
default system does not change.
volume-or-subvolume-names
is the name of your logon default volume or subvolume or both. These are your
current defaults when you log on or enter the VOLUME command without any
parameters.
For volume-or-subvolume-names, specify one of:
$default-volume-name
default-subvolume-name
$default-volume-name.default-subvolume-name
$default-volume-name
is the name of your new logon default volume. If you omit $defaultvolume-name, the current default volume is your new logon default.
default-subvolume-name
is the name of your logon default subvolume. If you omit defaultsubvolume-name, the current default subvolume becomes your new
logon default.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-53
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E F A U LT P ro gram
default-security
is the default disk file security that is to be in effect when you log on or enter the
VOLUME command without any parameters. (The current default file security is
assigned to newly created disk files unless you explicitly assign a different security
setting when you create a file.) For default-security, specify a string of four
characters inside quotation marks; the four characters represent the four security
attributes:
R W E P
R
specifies who can read the file.
W
specifies who can write to the file.
E
specifies who can execute the file.
P
specifies who can purge the file.
Each security attribute (R, W, E, and P) can be any of these characters:
O
(Owner) Only the owner can access the file; the owner must be
logged onto the local system.
(Group) Anyone in the owners group can access the file; the user
must be logged onto the local system.
(Anyone) Any user can access the file; the user must be logged onto
the local system.
(User) Only the owner can access the file; the owner may be logged
onto thelocal system or a remote system.
(Community) Anyone in the owners group can access the file; the
user may be logged onto the local system or a remote system.
(Network) Any user can access the file; the user may be logged onto
the local system or a remote system.
Considerations
During an operating session, you can change the current default values with the
SYSTEM and VOLUME commands. TACL uses the current default system,
volume, and subvolume names to expand partial file names. When you create a
file, it is assigned the default disk file security unless you explicitly specify a
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-54
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E F A U LT P ro gram
different security. For more information about changing the default values and
about disk file security, see the Guardian Users Guide.
Any new logon default values you set with the DEFAULT program do not take
effect until the next time you log on or until you enter the VOLUME command with
no parameters.
The current default settings are often different from your saved logon default
settings. When you log on, your logon default settings are in effect for system (if
you are on a network), volume, subvolume, and file security. After you log on, you
can change the current default volume or system with the VOLUME or SYSTEM
command. Neither of these commands, however, affects your logon default
settings. Every time you log on or enter a VOLUME or SYSTEM command with no
parameters, your logon default settings are restored. If you have changed these
settings with the DEFAULT program, the new values are in effect. For more
information, see the descriptions of the VOLUME Command on page 8-256, and
SYSTEM Command on page 8-221.
The TACL process creates a root segment, even if the default volume doesn't
exist. Users can logon even if the default volume doesn't exist.
Avoid specifying your current local system as the default system: Doing so is
unnecessary, and can in fact cause problems with some programs.
You cannot use the security specifier - (allow access to local super ID only) with
the DEFAULT program.
When a new user is added, the logon defaults are:
Volume $SYSTEM
Subvolume NOSUBVOL
Security AAAA
Example
Assume that you want your logon default volume to be $BIG, and your logon default
subvolume to be BAD. You also want your logon default disk file security to:
Allow any user on any system to read and execute a file with your default security
Allow only you, the owner of a file, to write to and purge a file with the default
security. (In addition, you must be logged onto the system where the file resides to
be able to write to such a file or to purge it.)
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E LE T E D E F IN E C o m m a n d
Considerations
The DELETE DEFINE command affects only DEFINEs for the current TACL
process. Any DEFINE that was propagated from the current TACL to other
processes is unaffected.
You cannot delete the =_DEFAULTS DEFINE.
To obtain error information, use the #ERRORNUMBERS Built-In Variable on
page 9-160.
Example
To delete the DEFINE named =DFILE, enter:
63> DELETE DEFINE =DFILE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-56
U T IL S :T A C L C om m an d s a nd F u nctio ns
D E LU S E R P ro gram (G ro up M a na ge rs O nly)
Consideration
Group managers can delete only those users who are members of their respective
groups. The super ID can delete any user in the system.
Example
The group manager of the BIG group (or the super ID) can delete the user BIG.BOZO
(user ID 7,12) by entering:
14> DELUSER BIG.BOZO
BIG.BOZO (7,12) HAS BEEN DELETED FROM THE USERID FILE.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-57
U T IL S :T A C L C om m an d s a nd F u nctio ns
DETACHSEG Command
Use the DETACHSEG command to relinquish use of a segment file.
DETACHSEG directory-name
directory-name
is the name of a directory whose variables are in another segment file.
Considerations
All segment files attached to it are detached from it. If you later attach the
segment file again, those segment files are not automatically attached again.
All variable levels within the segment are set to frame 0. This does not destroy
any variable levels, but gives the appearance that all variable levels were
created in frame 0.
There is a delay while TACL writes the segment file. TACL writes only as much
as has been used, not the whole file.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-58
U T IL S :T A C L C om m an d s a nd F u nctio ns
If the CPU on which your TACL process is running fails while you are in the act of
detaching a private segment file, the segment file may be corrupted. Any future
attempts to attach that file will fail. You must purge it and re-create it.
Note. ATTACHSEG operates by pushing and defining a directory variable that refers to the
specified segment file; DETACHSEG operates by popping that directory variable. Because
#UNFRAME pops all variables pushed since the most recent #FRAME, if you attach a segment
file following a #FRAME, the corresponding #UNFRAME detaches the segment file; its
contents are no longer available. Subsequent attempts to invoke those contents result in
errors.
Example
This command detaches the segment file that is attached to the directory variable
MYDIR:
25> DETACHSEG :mydir
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-59
U T IL S :T A C L C om m an d s a nd F u nctio ns
ENV Command
Use the ENV command to display the settings of one or all the environmental
parameters for your TACL.
ENV [ environment-parameter ]
environment-parameter
is one of these:
HOME
INLECHO
INLOUT
INLPREFIX
INLTO
PMSEARCH
SYSTEM
USE
VOLUME
HOME
displays the name of your current home directory. You set this value with the
HOME command.
INLECHO
displays the setting, OFF or ON, of the #INLINEECHO Built-In Variable on
page 9-200, which controls whether TACL copies to its own OUT file the lines it
sends as input to inline processes.
INLOUT
displays the setting, OFF or ON, of the #INLINEOUT Built-In Variable on
page 9-202, which controls whether TACL copies to its own OUT file lines sent
by inline processes to their OUT files.
INLPREFIX
displays the (possibly null) value of the #INLINEPREFIX Built-In Variable on
page 9-203, which contains the character or characters constituting the prefix
that identifies lines to be passed to inline processes.
INLTO
displays the (possibly null) value of the #INLINETO Built-In Variable on
page 9-206, which contains the name of a variable to which are appended
copies of lines sent by inline processes to their OUT files, if such a variable has
been defined.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-60
U T IL S :T A C L C om m an d s a nd F u nctio ns
PMSEARCH
displays the search list that your TACL uses to find program and macro files
when they are invoked implicitly. This list is set with the PMSEARCH
Command on page 8-118.
SYSTEM
displays the (possibly null) name of your current default system. You set and
clear this value with the SYSTEM Command on page 8-221.
USE
displays the directories that TACL searches for variables not found in your
home directory. You set this list with the USE Command on page 8-231.
VOLUME
displays the name of your current default volume, including the name of your
current default system if it is different from your saved default system. Your
current default file security is also defined. You set these values with the
VTREE Command on page 8-258.
Consideration
If you do not specify any parameter, ENV displays the settings of all your TACL
environment parameters.
Examples
To display your current default system, volume, subvolume, and file security, enter:
14> ENV VOLUME
Volume \MYSYS.$WORK.PROJECT, "NUNU"
To display all the environment parameters for your TACL process, enter ENV. This
output is returned:
15> ENV
Home
Inlecho
Inlout
Inlprefix
Inlto
Pmsearch
System
Use
Volume
:MYDIR
OFF
ON
#
#DEFAULTS, $SYSTEM.SYSTEM
:MYDIR.1, :, :UTILS.1, :UTILS.1:TACL.1
\MYSYS.$WORK.PROJECT, "NUNU"
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-61
U T IL S :T A C L C om m an d s a nd F u nctio ns
E X IT C o m m a n d
EXIT Command
Use the EXIT command to stop the current TACL process or TACL process pair.
Pressing CTRL-y is the same as typing EXIT.
EXIT
Considerations
To use the EXIT command to delete a TACL process on your home system, you
must be logged onto that system. You can, however, use EXIT to delete a TACL
process you started on a remote system without logging onto the remote system.
If TACL encounters an EXIT command or an end-of-file (EOF) while executing an
OBEY command file, command execution halts and control returns to the TACL
process in which the OBEY command was entered.
If TACL encounters an EXIT command while executing commands from an input
file (such as an IN file named in the command to start a TACL process), and TACL
is not running interactively, the TACL process is deleted. Control returns to the
process from which TACL was started.
If you enter an EXIT command from the terminal when both IN and OUT refer to
that terminal (the interactive mode), TACL asks:
Are you sure you want to stop this TACL ( process-spec)?
To stop the current TACL, enter Y, YE, or YES followed by a RETURN. This may make
your terminal unavailable to the system (see the note, below). If you enter any other
character or only a RETURN, TACL ignores the EXIT command.
Note. If you delete your last TACL process, you cannot communicate with the system from
your terminal. You can, however, use another terminal to start a new TACL process on your
terminal. (See the syntax description for the TACL Program on page 8-224.)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-62
U T IL S :T A C L C om m an d s a nd F u nctio ns
FC Com m and
FC Command
Use the FC command to retrieve, edit, and reexecute lines in the history buffer.
FC [ num | -num | text ]
num
is a positive integer that refers to the specific command-line number you want to
retrieve from the history buffer.
- num
is a negative number that refers to a command line in the history buffer relative to
the current command line.
text
is the most recent command line in the history buffer that begins with the text you
specify. This text need only be as many characters as necessary to identify the
command line.
Consideration
When you enter the FC command, the specified command line is redisplayed (if you do
not specify a line, the most recent command line is redisplayed). A double period
prompt (..) appears below it.
Examples
Suppose that you are renaming the file JUNK to TESTFILE, and make a typing error in
the RENAME command on line 9. Rather than retype the whole line, type FC 9 to fix
the invalid command:
12> FC 9
12> RENMAE JUNK, TESTFILE
12..
You now see your invalid command redisplayed on the screen. The blank line at the
double period prompt is an editing template. In this template, you enter subcommands
that make corrections or additions to the command displayed above the template. The
rules for entering subcommands and for making corrections and additions are
described for the Editing Template on page 8-64.
After you enter the subcommands you want, press the RETURN key. Your edited
command and a new editing template then appear. If you want to make more
corrections to the edited command, you can enter more subcommands in the editing
template and then press RETURN. If the edited command is correct, you can
reexecute it by pressing RETURN without entering any subcommands.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-63
U T IL S :T A C L C om m an d s a nd F u nctio ns
FC Com m and
Editing Template
The syntax of the editing template is:
subcommand [ // subcommand ] ...
subcommand is any of these:
{ R | r } replacement-text
{ I | i } insertion-text
{ D | d }
replacement-text
//
is a separator, allowing multiple subcommands on a given line. A subcommand
can immediately follow one or more uppercase or lowercase Ds without being
preceded by //.
{ R | r } replacement-text
replaces characters in the previous command, starting with the character
displayed immediately above the R or r. A replacement-text preceded by R or r
can be any string of characters, including spaces, and can itself begin with R, I,
or D (or r, i, or d). Characters in replacement-text replace characters in the
previous command on a one-for-one basis.
If // follows this subcommand, all characters in replacement-text up to //,
including spaces, replace characters in the previous command. Otherwise,
replacement ends with the RETURN.
{ I | i } insertion-text
inserts characters into the previous command in front of the character
displayed above the I or i. If // follows this subcommand, all characters in
insertion-text up to //, including spaces, are inserted into the previous
command. If no // appears, all characters up to the RETURN are inserted.
{ D | d }
deletes characters in the previous command. Any original character displayed
above a D or d that begins a subcommand in the editing template is deleted.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-64
U T IL S :T A C L C om m an d s a nd F u nctio ns
FC Com m and
replacement-text
is any text that does not begin with R, I, or D (or r, i, or d). Characters in
replacement-text replace characters immediately above them on a one-forone basis. For example, a D in replacement-text replaces the character
displayed above it instead of deleting it.
Considerations
Examples
1. This example demonstrates the use of subcommands D, R, and I and the
subcommand separator (//):
11> COMMENT
12> FC
12> COMMENT
12.. DRis//
12> COMMENT
2. This example retrieves the command line numbered 5 in your history buffer:
13> FC 5
13> WHOM
13..
3. This example retrieves the third command back from your current command-line
number:
14> FC -3
14> COMMENT This are a commnt
14..
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-65
U T IL S :T A C L C om m an d s a nd F u nctio ns
FC Com m and
4. This example retrieves the most recent line in your history buffer that begins with
the text STA:
15> FC STA
15> STATUS *, TERM
15..
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-66
U T IL S :T A C L C om m an d s a nd F u nctio ns
F ILE IN F O C o m m a n d
FILEINFO Command
Use the FILEINFO command to display information about one or more disk files. The
FILEINFO command allows the use of a file-name template. The FILEINFO command
is an alias for the #XFILEINFO Built-In Function on page 9-420.
FILEINFO [ / OUT list-file / ]
[ file-name-template [ [,] file-name-template ] ... ]
OUT list-file
specifies a device, or a sequential file accessible to the sequential I/O (SIO) facility,
that is to receive the output from FILEINFO. If you omit this option, TACL writes the
listing to its current OUT file.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
file-name-template
is a list of one or more disk file specifications separated by commas or spaces.
Each disk file specification must be formatted as follows:
[[[\node.]$volume.] subvolume.] file-name ]
If, however, you specify a volume name, you must specify a subvolume name. This
file name is not syntactically correct:
$volume-name.file-name
For a description of filename templates, see File-Name Templates on page 2-7.
Considerations
If you do not specify a file-name template, FILEINFO displays information about all files
in the default volume and subvolume.
When a file is copied from one system to another system in a different time zone
without modifying the source date of the file, the FILEINFO command returns the file
modification time as the local civil time of the system from which the file was copied.
FILEINFO displays information in a form similar to the following:
$SPOOL.LINDA
CODE
AFILE
EOF
LAST MODIFIED
0 07DEC2000 15:58
OWNER
RWEP
PExt
SExt
8,185 NUNU
showing the name of each file requested, one or more letters identifying the file status,
its file code, the size of the file, the date and time when it was last modified, the user ID
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-67
U T IL S :T A C L C om m an d s a nd F u nctio ns
F ILE IN F O C o m m a n d
of its owner, its file security, and the number of primary and secondary extents
allocated to it.
If the request is for a file that does not exist, the TACL process returns an error
message:
No files match \TSII.$SPOOL.LINDA.BFILE
If the request is formatted as $volume.filename, the TACL process returns an error
message:
FILEINFO $SPOOL.A
^
Expecting /
Or a valid filename template
Or end
The command output display provides this information:
Character
Position in
Output
Display
Field
Description
[1 - 8]
filename
[9 - 10]
blank
[11]
CODE:
Open File or
Crash-Open File
Indicator
CODE:
Corrupt File or
SQL DDL Free
Space Status
Indicator
CODE:
File Code
[12]
[14 - 18]
Field Value
Name of the file whose characteristics are being
displayed, left justified
O File is open.
? File was open during a crash and therefore the content
might have been compromised.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-68
U T IL S :T A C L C om m an d s a nd F u nctio ns
Character
Position in
Output
Display
[19 - 22]
Field
Description
CODE:
FLAGS
F ILE IN F O C o m m a n d
Field Value
"A" File is audited by TMF.
"L" File is licensed. See file licensing information in the
File Utility Program (FUP) Reference Manual.
P The PROGID attribute of the file is on. See file
PROGID information in the File Utility Program (FUP)
Reference Manual.
"+" File is a format 2 file. See format 2 file information in
the File Utility Program (FUP) Reference Manual.
[23 - 35]
EOF
0 File is empty.
n through nnnnnnnnnnnnn File size in bytes
"*************" File size display exceeds 13 digits.
[36]
blank
[37 - 45]
LAST
MODIFIED:
day, month, year
[46]
blank
[47 - 51]
LAST
MODIFIED:
hour, minute
[52]
blank
[53 - 59]
OWNER
ggg,uuu
The group number and user number that identify the file
owner
Note: The super ID (255,255) is displayed as -1.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-69
U T IL S :T A C L C om m an d s a nd F u nctio ns
Character
Position in
Output
Display
Field
Description
[60]
blank
[61 - 64]
RWEP
F ILE IN F O C o m m a n d
Field Value
File security assigned to the file for read, write, execute,
and purge access.
"****" File access is controlled with Safeguard security.
"####" File access is controlled with OSS security.
xxxx File access is controlled with Guardian security:
- local super ID only
O local owner only
G local member of owner's group only
A any local user
U local or remote owner
C local or remote member of owner's group N any
local or remote user
For SQL/MX objects, the security options RWEP are
displayed as *SQL.
See file security information in the File Utility Program
(FUP) Reference Manual.
[65]
blank
Examples
1. This example illustrates the use of FILEINFO with a fully qualified file name:
15> FILEINFO \SOFTW.$BOOKS.TACL.V1SEC2B
2. The next example illustrates the use of the file-name template characters. The
asterisk (*) in the subvolume indicates that you want TACL to search for any
subvolume that begins with BOOK. The question mark (?) in the file name
indicates that you want information about any file whose name has SEC in the first
three positions, any character in the fourth position, and a 2 in the fifth position.
16> FILEINFO BOOK*.SEC?2
3. An even more generalized command is:
17> FILEINFO $VOL*A.*.SEC*2
which searches for any volume whose name begins with $VOL and ends with A,
all subvolumes on those volumes, and any file in those subvolumes whose name
begins with SEC and ends with 2. Note that in the previous example, SEC02,
SEC12, SECT2, and so on, meet the search criteria; in this example, SEC2,
SECT02, and SECT9992 also qualify.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-70
U T IL S :T A C L C om m an d s a nd F u nctio ns
F IL E N A M E S C o m m a n d
FILENAMES Command
Use the FILENAMES command to display the names of all files that satisfy the filename specifications in the file-name-template. The FILENAMES command is an
alias for the #XFILENAMES built-in function.
FILENAMES [ / OUT list-file / ]
[ file-name-template [ [,] file-name-template ] ... ]
OUT list-file
specifies a device, or a sequential file accessible to the sequential I/O (SIO) facility,
that is to receive the output from FILENAMES. If you omit this option, TACL writes
the listing to its current OUT file.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
file-name-template
is a list of one or more disk file specifications separated by commas or spaces.
Each disk file specification must be formatted as follows:
[[[\ node-name.]$ volume-name.] subvolume-name.] file-name
For a description of file-name templates, see Section 2, Lexical Elements.
Consideration
If you do not include any file-name template, FILENAMES lists all files in your default
volume and subvolume.
Examples
This example illustrates the output of the FILENAMES command:
17> FILENAMES $BOOKS.TACL.SEC*
$BOOKS.TACL
SEC01 SEC02A SEC02B SEC02C SEC02D
18>
The asterisk in the file-name template instructs FILENAMES to display the names of all
files that begin with SEC, regardless of which, or how many, characters follow.
This example illustrates the use of two file-name template characters. The asterisk (*)
in the subvolume indicates that you want TACL to search for any subvolume that
begins with BOOK. The question mark (?) in the file name indicates that you want to
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-71
U T IL S :T A C L C om m an d s a nd F u nctio ns
F IL E N A M E S C o m m a n d
list the name of any file whose name has SECT in the first four positions, any character
in the fifth position, and a 2 in the sixth position:
18> FILENAMES $smith.book*.sect?2
$SMITH.BOOK1
SECT02
$SMITH.BOOK2
SECT02 SECT12
19>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-72
U T IL S :T A C L C om m an d s a nd F u nctio ns
F ILE S C o m m a n d
FILES Command
Use the FILES command to display the names of files in one or more subvolumes.
FILES [ / OUT list-file / ]
[ subvol-template [ [,] subvol-template ] ... ]
OUT list-file
specifies a device, or a sequential file accessible to the sequential I/O (SIO) facility,
that is to receive the output from FILES. If you omit this option, TACL writes the
listing to its current OUT file.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
subvol-template
is a list of one or more disk subvolume specifications separated by commas or
spaces. Each subvolume specification must be formatted as follows:
[[[\node-name.]$volume-name.] subvolume-name ]
For a description of subvolume-name templates, see Subvolume Templates on
page 2-7.
Consideration
If you do not include any subvol-template, FILES lists all files in your default volume
and subvolume.
Examples
1. You can list the files in your current default subvolume by entering:
34> FILES
2. To list the files in all subvolumes in your current default volume, enter:
35> FILES *
3. To list the files in all subvolumes that begin with SYS in the volume $SYSTEM,
enter:
36> FILES $SYSTEM.SYS*
4. To list the files in subvolume SUBZ in volume $DISC1 of the system \ROME, enter:
37> FILES \ROME.$DISC1.SUBZ
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-73
U T IL S :T A C L C om m an d s a nd F u nctio ns
F IL E T O V A R C o m m a n d
FILETOVAR Command
The FILETOVAR command copies data from a file and appends it to a variable level.
FILETOVAR file-name variable-level
file-name
is the name of an existing file from which data is to be copied. It must be readable
by the sequential I/O facility (SIO). Both format1 and format 2 files are supported.
variable-level
is the name of an existing variable level to which the copied data is to be
appended. The variable must not be in a shared segment and must not be a
directory, a STRUCT, or a STRUCT item.
Considerations
Lines longer than 239 characters in the file are truncated to 239 characters when they
are appended to the variable level.
File I/O appears in PLAIN format, which means that no special interpretation is given to
the TACL metacharacters [, ], |, ==, {, and } when they are read. In particular, this
means that you cannot copy TACL statements from a file to a variable unless you
wrote the statements into the file with the VARTOFILE command originally. (When
TACL loads code from a file into a variable, it processes metacharacters to produce
executable code, but FILETOVAR only moves text into the variable.)
Another, faster way to append data to a variable level is to use the #SET command:
#SET /IN file-name/ variable
As with the FILETOVAR command, TACL INFORMAT must be set to PLAIN when
using the #SET function in this manner.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-74
U T IL S :T A C L C om m an d s a nd F u nctio ns
H E LP C o m m a n d
HELP Command
The HELP command displays a single screen of general information about TACL.
HELP
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-75
U T IL S :T A C L C om m an d s a nd F u nctio ns
H IS T O R Y C o m m a n d
HISTORY Command
Use the HISTORY command to display the most recently executed command lines.
HISTORY [ num ]
num
is the number of commands to display. By default, num is 10.
Considerations
The HISTORY command displays the specified number of lines in the history
buffer. The history buffer is 1000 characters long and contains zero or more lines.
Each line stored in the history buffer requires as many bytes as the line contains,
plus one extra byte.
The lines TACL retains in its history buffer are those nonblank lines you type in, not
the lines TACL executes.
Each line that an FC command or exclamation point command causes to be
repeated becomes a new line in the history buffer, just as if you had typed the
command again.
If you type a line too long to fit into the history buffer, TACL executes the line
properly but omits it from the buffer.
If the number is larger than the history buffer, TACL returns the number of available
lines.
If the number is too large, TACL returns an error.
Example
This example illustrates how to list the last five command lines. TACL lists the previous
five lines, including the HISTORY command:
32>
28>
29>
30>
31>
32>
HISTORY 5
ENV
FILEINFO BOOK*.SEC
SET DEFINE CLASS MAP
SET DEFINE FILE RSLTS
HISTORY 5
33>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-76
U T IL S :T A C L C om m an d s a nd F u nctio ns
HO M E Com m and
HOME Command
Use the HOME command to specify the first directory in which your TACL process
searches for variables before searching any other directories.
HOME [ directory-name ]
directory-name
is the name of an existing variable level of type DIRECTORY. If omitted, the root (:)
is assumed.
Considerations
Example
This command establishes the directory variable ANOTHER_DIR, within the directory
variable MYDIR, as the home directory:
24> HOME :mydir:mykeys
To list the home directory, you can use the ENV command. It returns this output:
25> ENV
Home
Inlecho
Inlout
Inlprefix
Inlto
Pmsearch
System
Use
Volume
:MYDIR:mykeys
OFF
ON
$SYSTEM.SYSTEM, $DATA.MYFILES, #DEFAULTS
:, :UTILS.1, :UTILS.1:TACL.1
$DATA.MYFILES, "AAAA"
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-77
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN F O D E F IN E C o m m a n d
Considerations
If you omit the DETAIL option, the INFO DEFINE command displays only three
items: the name of the DEFINE, its CLASS, and an attribute that depends on the
class. If you include the DETAIL option, the display lists every attribute that has a
value, along with that value. The examples that follow show both types of display.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-78
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN F O D E F IN E C o m m a n d
You cannot display the names of attributes to which no values have been
assigned.
You can display all DEFINEs by entering INFO DEFINE ** or INFO DEFINE =*.
DEFINEs are displayed in ASCII sort sequence by name.
To obtain error information, use the #ERRORNUMBERS Built-In Variable on
page 9-160.
Examples
1. To display the CLASS and the principal attribute of all DEFINEs enter:
13> INFO DEFINE **
Define Name
CLASS
FILE
Define Name
CLASS
VOLUME
=ACK
MAP
$BILL.THECAT.ACKPHTH
=_DEFAULTS
DEFAULTS
$BILL.THECAT
2. This command displays the principal attributes of all the DEFINEs with names that
match a template pattern:
14> INFO DEFINE =A*
Define Name
CLASS
FILE
=ACK
MAP
$BILL.THECAT.ACKPHTH
3. To display all the attributes (that have values) of an existing DEFINE, enter:
15> INFO DEFINE =TEST3, DETAIL
DEFINE NAME
=TEST3
CLASS
TAPE
VOLUME
SCRATCH
LABELS
OMITTED
USE
IN
DEVICE
$TAPE2
MOUNTMSG
"Transferring files, low pri.-Fred"
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-79
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN IT T E R M C o m m a n d
INITTERM Command
Use the INITTERM (initialize terminal) command to reinstate the default attributes of
your home terminal. The INITTERM command is an alias for the #INITTERM Built-In
Function on page 9-199.
INITTERM
Considerations
Typically, you use the INITTERM command when an application program has left your
terminal in an abnormal state. INITTERM calls the SETMODE procedure, function 28.
For information about setting device attributes, see the description of SETMODE
settings for terminals in the Guardian Users Guide and the description of the
SETMODE procedure in the Guardian Procedure Calls Reference Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-80
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN LE C H O C o m m a n d
INLECHO Command
Use the INLECHO command to specify whether lines sent as input to an inline process
are to be copied to the current TACL OUT file. (Use of the INLINE facility is described
in the TACL Programming Guide.)
INLECHO { OFF | ON }
OFF
disables echoing of input lines.
ON
enables echoing of input lines to the TACL OUT file.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-81
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN L E O F C o m m a n d
INLEOF Command
Use the INLEOF command to send an end-of-file indication to an inline process. (Use
of the INLINE facility is described in the TACL Programming Guide.)
INLEOF
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-82
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN L O U T C o m m a n d
INLOUT Command
Use the INLOUT command to specify whether lines written by inline processes to their
OUT files are to be copied to the current TACL OUT file as well. (Use of the INLINE
facility is described in the TACL Programming Guide.)
INLOUT { OFF | ON }
OFF
disables copying of output lines.
ON
enables copying of output lines to the TACL OUT file.
Considerations
To permit OUT file copying, the inline process must have been started with neither
the OUT option nor the OUTV option.
The INLOUT command offers a simplified interface to the #INLINEPREFIX Built-In
Variable on page 9-203.
You can display the current setting for INLOUT with the ENV command.
You can save the previous copy-control setting by pushing #INLINEOUT; you can
revert to that setting by popping #INLINEOUT.
CONTROLs and SETMODEs issued by an inline process are ignored.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-83
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN L P R E F IX C o m m a n d
INLPREFIX Command
Use the INLPREFIX command to establish the prefix that identifies lines that are to be
passed as input to inline processes. (Use of the INLINE facility is described in the
TACL Programming Guide.)
INLPREFIX [ prefix ]
prefix
is one or more characters constituting a prefix that, when placed at the beginning
of a TACL input line and followed by a space, identifies the remainder of the line as
input to be passed to an inline procedure instead of being acted upon by TACL.
Considerations
Example
This command establishes @@ as the inline prefix:
327> INLPREFIX @@
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-84
U T IL S :T A C L C om m an d s a nd F u nctio ns
IN LT O C o m m a n d
INLTO Command
Use the INLTO command to establish a variable level that is to receive copies of lines
written by inline processes to their OUT files. TACL appends copied lines to the end of
the variable level. (Use of the INLINE facility is described in the TACL Programming
Guide.
INLTO [ variable-level ]
variable-level
is the name of an existing variable level.
Considerations
To permit OUT file copying, the inline process must have been started with neither
the OUT option nor the OUTV option.
The INLTO command offers a simplified method of setting the #INLINETO Built-In
Variable on page 9-206.
You can display the current setting for INLTO with the ENV command.
You can save the previous output variable identity by pushing #INLINETO; you can
revert to that output variable by popping #INLINETO.
variable-level must not be a DIRECTORY, a STRUCT, or a STRUCT item.
If you omit variable-level, the copying feature is disabled.
Example
This command defines KEEPER as the variable level to receive inline process output.
329> INLTO keeper
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-85
U T IL S :T A C L C om m an d s a nd F u nctio ns
IP U C O M P ro gram
IPUCOM Program
Use the IPUCOM program for a command line interface which can be used to set,
reset, or display an IPU number associated with a process. It can also be used to set
or display CPU-wide controls.
Note.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-86
U T IL S :T A C L C om m an d s a nd F u nctio ns
IP U C O M P ro gram
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-87
U T IL S :T A C L C om m an d s a nd F u nctio ns
IP U C O M P ro gram
Considerations
The IPUCOM program can be run without super-group or other privileges, but to
alter any of the process or CPU-wide settings, the user must conform to the
security requirements of a corresponding call to IPUAFFINITY_SET_ or
IPUAFFINITY_CONTROL_.
See the Guardian Procedure Calls Reference Manual for details on the
requirements of those interfaces.
Note that in particular the user of IPUCOM must be locally logged in to alter any of
the process or the CPU-wide settings.
A customer may choose to give the IPUCOM program to a SUPER group member
and then set PROGID on it. They can then use either Safeguard ACLs or standard
file security to control execution access. It is not shipped with PROGID set.
For more information about the restrictions and requirements on the use of IPUCOM,
see the considerations for the IPUAFFINITY_GET_, _SET_, and _CONTROL_
procedures in the Guardian Procedure Calls Reference Manual.
Examples
The following example sets the primary $XYZ process on IPU 1:
IPUCOM -pname $xyz 1
The following unbinds the primary $XYZ process, allowing it to be moved again by the
process scheduler:
IPUCOM -pname $xyz unbind
The following displays the IPU affinity of the $XYZ process:
IPUCOM -pname $xyz info
The following sets the process that is PIN 456 in CPU 3 on IPU 2:
IPUCOM -pin 456 -cpu 3 2
The following turns off DP2 balancing in the process scheduler in CPU 5:
IPUCOM -cpu 5 -balanceDP2 off
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-88
U T IL S :T A C L C om m an d s a nd F u nctio ns
JO IN C o m m a n d
JOIN Command
Use the JOIN command to convert a multiple-line variable level into a single-line
variable level, replacing each internal end-of-line with a single space.
JOIN variable-level
variable-level
is the name of an existing variable level.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-89
U T IL S :T A C L C om m an d s a nd F u nctio ns
KEEP Command
Use the KEEP command to remove all but the top num definition levels of one or more
variables.
KEEP [ / LIST / ] num variable [ variable ] ...
LIST
causes KEEP to display each variable name followed by the number of levels
removed from that variable.
num
is the number of levels to keep.
variable
is the name of an existing variable.
Consideration
KEEP 0 deletes the variable.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-90
U T IL S :T A C L C om m an d s a nd F u nctio ns
KEYS Command
Use the KEYS command to display the current function key definitions.
KEYS
Example
This example is a sample KEYS command display; the values vary depending on how
the TACL environment is set up:
127> KEYS
F16
= (The Help Key)
F1
= #OUTPUT TEDIT %1%; %2 to *%
TEDIT %1%; %2 to *%
#OUTPUT Finished editing [#SHIFTSTRING/UP/%1%]
F2 =
#OUTPUT TFORM /IN %1%, OUT $S.#%2%, NOWAIT/ %3 to *%
TFORM /IN %1%, OUT $S.#%2%, NOWAIT/ %3 to *%
F3 =
TYPE %1%
***
SF15 =
SF16 =
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-91
U T IL S :T A C L C om m an d s a nd F u nctio ns
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-92
U T IL S :T A C L C om m an d s a nd F u nctio ns
ALL
turns on every sys-option at once (DISPATCHES, SYSPROCS, and PAGING).
BEAT
flashes light 0 (zero) once every second to indicate that the processor is
functioning.
Considerations
Lights 0 through 10 indicate processor usage. Light 0 is always lit (or flashing if
BEAT was specified). One additional light is lit for each 10 percent increase in
processor usage.
When the system is cold loaded, the default LIGHTS setting is ON, ALL, BEAT.
Examples
1. To turn on the processor lights and have them show processor usage smoothed
over 10-second intervals, enter:
94> LIGHTS SMOOTH
2. To change the display to show processor usage for 25-second intervals, enter:
95> LIGHTS SMOOTH 25
3. To turn on processor light 15 whenever paging activity occurs, enter:
96> LIGHTS ON, PAGING
4. To turn on light 14 whenever a system process is executed, and light 13 after each
100 dispatches, enter:
97> LIGHTS, SYSPROCS, DISPATCHES
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-93
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO AD Com m and
LOAD Command
Use the LOAD command to load one or more TACL library files into the TACL memory.
LOAD [ / KEEP num / ] file-name [ file-name ] ...
KEEP num
causes TACL, after executing the LOAD command, to perform an implicit KEEP
command on all the variables modified by the LOAD command.
file-name
is the name of one or more TACL libraries.
Considerations
Each library consists of one or more ?SECTION directives that specify a variable
and a type associated with that variable, followed by the information (body) to be
put into it when it is created.
To process a file, TACL does this for each ?SECTION directive: it pushes the
variable, sets its contents to type, and makes body the new top-level definition of
the variable.
As a library is loaded, comments are removed to conserve variable space. Any line
that is blank, or becomes blank because of comment removal, is discarded.
If you need to include a blank line (often useful in DELTA type variables), use the
?BLANK directive. ?BLANK causes the loader to insert a blank line in the variable
level.
To include lines beginning with question marks (for example, you might be loading
DDL commands into a variable level for later use as the IN variable for a DDL run),
double the question mark (??). The first question mark and any spaces adjacent to
it are discarded and the remainder of the line is treated as text.
The LOAD command reads data from a library file in TACL format unless the file
contains a ?FORMAT PLAIN or ?FORMAT QUOTED directive to specify otherwise.
If changed, the format reverts to TACL at the next ?SECTION directive.
Example
This example illustrates how to load two libraries, retaining only one level of each
variable:
17> LOAD / KEEP 1 / mykeys mymacs
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-94
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO A D E D F ILE S C o m m a n d
LOADEDFILES Command
Use the LOADEDFILES command to display information about the load files that are
being used by the specified process.
LOADEDFILES [ / OUT list-file / ][ \node-name ] &
{ $Process-name | CPU, PIN|}
OUT list-file
specifies a device or sequential file accessible to the sequential I/O (SIO) facility
that is to receive the output from the command. If you omit this option, TACL writes
the listing to the current OUT file.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
\node-name
is the name of the system on which the specified process executes.
$Process-name or CPU, PIN
is the name of the process or process pair. Alternatively, use the CPU number and
process identification number of the process.
Type - the type of loaded file; it can be any one of these types:
N-PROG: a native program (non-PIC).
P-PROG: a native program (PIC)
UC-R: a TNS program (accelerated)
UC: a TNS program (non-accelerated)
UL-R: a TNS User Library (accelerated)
UL: a TNS User Library (accelerated)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-95
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO A D E D F ILE S C o m m a n d
Considerations
Example
$DATA08 KIRAND 10> loadedfiles \bombay.0,11
PROCESS NAME =
$ZL00
TYPE
FILENAME
NPROG
\BOMBAY.$SYSTEM.SYS01.ROUT
SRL
\BOMBAY.$SYSTEM.SYS01.ZCRESRL
SRL
\BOMBAY.$SYSTEM.SYS01.ZI18NSRL
SRL
\BOMBAY.$SYSTEM.SYS01.ZICNVSRL
SRL
\BOMBAY.$SYSTEM.SYS01.ZCRTLSRL
SRL
\BOMBAY.$SYSTEM.SYS01.ZCPLGSRL
SRL
\BOMBAY.$SYSTEM.SYS01.ZOSSKSRL
SRL
\BOMBAY.$SYSTEM.SYS01.ZTLHGSRL
Total No. of Loadedfiles = 8
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-96
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O F F C o m m a n d
LOGOFF Command
Use the LOGOFF command to log off from the current TACL process. The LOGOFF
command is an alias for the #LOGOFF Built-In Function on page 9-252.
LOGOFF [ / option [, option ] ... / ]
option
is one of these options:
CLEAR
clears the terminal screen after you log off (for use when TACL is not
configured to clear the screen automatically).
NOCLEAR
prevents TACL from clearing the terminal screen after you log off (for use when
TACL is configured to clear the screen automatically, as is usually the case).
PAUSE
causes TACL to execute a PAUSE command immediately following the
LOGOFF command.
SEGRELEASE
causes TACL to release immediately the extended segment that held your
variables. Typically, TACL saves this segment in the event you later log onto
the same TACL; but if you fill up your variable space and processing cannot
proceed, you can log off using the SEGRELEASE option to discard the
variable space.
Considerations
When you log off, you terminate only your session with the current
TACL.Processes that you started can continue to run after you log off.
Any macro or routine running at the time #LOGOFF occurs terminates
immediately. A subsequent LOGON does not restart it.
Before logging off, you should stop processes that you are no longer using. Use
the STATUS Command on page 8-206 to see a list of the processes that are
running. Then use the STOP Command on page 8-215 to stop any unneeded
processes.
If you enter the LOGOFF command while working through a modem, the modem
disconnects (unless the ancestor of your TACL process is running in another
system, as above).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-97
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O F F C o m m a n d
If you are accessing a remote node through a modem on your local node, TACL
does not issue a modem disconnect.
After you log off, the current TACL process accessor ID and creator accessor ID
are set to NULL.NULL (0,0). This is also the setting of the accessor IDs when an
interactive TACL is started but no user has logged on.
After you log off, any process that tries to use your variables receives file-system
error 66 on its I/O requests.
Note. The LOGOFF command is an alias for the #LOGOFF built-in function. You can, if
you want, redefine LOGOFF as the name of a routine or macro of your own creation that
checks for variables in use by processes, requesters, and servers. You can then close
associated files and processes before logging off to avoid error-66 conditions.
If your TACL is interactive, and your terminal is a 6520 or 6530, and TACL is
configured to clear the terminal screen as a security measure (the default), it does
so when you log off. You can override the automatic screen clearing with the
NOCLEAR option. Conversely, if TACL is configured to omit automatic screen
clearing, you can use the CLEAR option to clear the terminal screen.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-98
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
LOGON Command
Use the LOGON command to establish communication with a TACL process. To enter
TACL commands interactively, you must first log on. However, when you execute TACL
commands from a command file (by specifying a disk file containing TACL commands
as the IN file when you start a new TACL process), you do not need to include the
LOGON command in the file.
Note. The LOGON command behavior depends on the Safeguard environment. If Safeguard
is not running on your system or if the USER_AUTHENTICATE procedure is not in the system
library, these logon options are not available:
alias
old-password, new-password
old-password, new-password, new-password.
LOGON
group-name.user-name | group-id,user- id | alias
[ password |
old-password new-password |
old-password new-password new-password
]
[ ; parameter [ , parameter ] ]
group-name.user-name or group-id,user-id
is the group name and user name, or the group number and user number, of the
user who is logging on. The user identity must already be established. If you do not
have a user account, see your system administrator. To do a blind logon, enter only
LOGON followed by your group-name.user-name or group-id, user-id
and press RETURN. TACL then prompts you for your password.
If the TACL configuration NAMELOGON option is not set to or if Safeguard is
running and the Safeguard NAMELOGON flag is set to 0 (for
USER_AUTHENTICATE_ call), the group number and user number is not
accepted.
alias
is an alternate assigned name. Each alias must be unique within the local system.
An alias is a case-sensitive text string that can be up to 32 alphanumeric
characters in length. In addition to alphabetic and numeric characters, the
characters period (.), hyphen (-), and underscore(_) are permitted within the text
string. The first character of an alias must be alphabetic or numeric. For more
information on aliases, see the Safeguard Reference Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-99
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
password
is the password associated with the user. You must include password if a password has been established for you. If you have a password, you must separate it
from your user name with a comma if you enter it before pressing RETURN. You
can also use the blind password feature by omitting the comma and password from
the LOGON command, then entering your password when prompted. For more
information about passwords, see the PASSWORD Program on page 8-115.
You can change your password as part of the logon sequence. Initially, the logon
dialog is the same as a normal logon. However, to indicate that you want to change
your password, type a comma at the end of your password. The system prompts
you for a new password and then requests reentry of the new password to verify it.
This dialog shows a sequence in which SUPPORT.JANE changes her password
from alpha4 to BigTop:
TACL 1> LOGON SUPPORT.JANE
Password: alpha4,
Enter new password: BigTop
Reenter new password: BigTop
The password for SUPPORT.JANE has been changed.
An alternative method of changing a password is to enter the current password, the
new password, and the verification of the new password on the same line. This
dialog shows this type of password change:
TACL 1> LOGON SUPPORT.JANE
Password alpha4, BigTop, BigTop
The password for SUPPORT.JANE has been changed.
Another option for changing the password is to enter the current and new
passwords on one line and the verification of the new password on the new line.
TACL 1> LOGON SUPPORT.JANE
Password alpha4, BigTop
Reenter new password: BigTop
The password for SUPPORT.JANE has been changed.
parameter
is an operating parameter for the TACL process. It can be one of these:
ABENDONABEND
HOMETERM
SEGVOL $ volume-name
STOPONABEND
Note. Parameters can be specified only when you are logging on from the logged-off
state. You cannot specify parameters when you are logging on from the logged-on state.
ABENDONABEND
specifies that TACL abends with an abend completion code and displays an
error message to the current OUT file when a process started by this TACL
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-100
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
Considerations
When you log on, the operating system displays a logon message that usually
includes:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-101
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
The number of the processor in which the primary and backup TACL process is
running
When you enter a full LOGON command, your identity and password are displayed
on the terminal screen; if you want to assure security, you can use the blind
password feature.
When you enter the LOGON command, your logon (saved) default values are in
effect for system, volume, and subvolume names and for disk file security. (See the
DEFAULT Program on page 8-53 for information about logon default values.)
After you log on, the current TACL process accessor ID and creator accessor ID
are set to the accessor ID associated with your user name. If your logon fails
because you try an invalid or undefined user name or password, the accessor IDs
remain set at 0,0. (This is the accessor ID setting when an interactive TACL is
started and no user has logged on.)
A logon failure occurs if either the $CMON process or the
USER_AUTHENTICATE_ procedure denies the logon but not if you make a syntax
error in the LOGON command. If a logon failure occurs, TACL displays an Invalid
username or password message, without specifying which element was in error. If
successive logon failures occur, TACL can prevent further logons for a specific
period of time, depending on Safeguard and USER_AUTHENTICATE_ security
logic. Until a successful logon occurs, all subsequent logon failures also initiate this
delay.
If the USER_AUTHENTICATE_ procedure fails to recognize the user information
given during the logon operation, the TACL built-in variable #ERRORNUMBERS
contains the error information. To display the error information, issue these
commands:
#PUSH n1 n2 n3 n4
#SETMANY n1 n2 n3 n4, [#ERRORNUMBERS]
where:
n1 = 1074 (Invalid user name or password)
n2 = error return from USER_AUTHENTICATE_
n3 = error return detail from USER_AUTHENTICATE_
n4 = 0
If n2 contains 0 (no error state returned), USER_AUTHENTICATE_ is not in the
system library or Safeguard is not running. If Safeguard is not running, n3 and n4
are set to 0.
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
When you enter a full LOGON command, your identity and password are displayed
on the terminal screen. You can use the blind password feature in the TACL
configuration or in Safeguard to ensure security.
The process accessor ID and creator accessor ID of the user logging on are
propagated to any descendant processes of TACL. (For a description of accessor
IDs, see the Guardian Users Guide.)
If you are logged on as the super ID, you can log on as any user in your system
without giving that users password. Similarly, if you are a group manager, you can
log on as any member of your group without giving that users password.
Entering the LOGON command from a logged-off state clears all assignments you
made with the ASSIGN and PARAM commands, clears all DEFINEs, and resets
the Inspect setting to the default value of OFF (see the SET INSPECT Command
on page 8-193 for information about Inspect settings). But if you log on without
explicitly logging off the previous user, the assignments, parameters, and DEFINEs
are retained, and the current Inspect setting remains in effect (see Example 3 on
page 8-106).
The ability to log on from a logged-on state can be disabled by setting the TACL
configuration option NOCHANGEUSER to -1. To display the value of
NOCHANGEUSER, use #GETCONFIGURATION /NOCHANGEUSER/.
If the TACL configuration option BLINDLOGON is not set to 0 or if Safeguard is
running and the Safeguard NAMELOGON flag is not set to 0 (for
USER_AUTHENTICATE_ call), the use of the comma is prohibited. The password
must be entered at its own prompt while echoing is disabled. To display the value
of BLINDLOGON, use #GETCONFIGURATION /BLINDLOGON/.
If the TACL configuration option REMOTECMONREQUIRED is not set to 0, all
operation requiring approval by remote $CMON are denied if that remote $CMON
is unavailable or is running too slowly. To display the value of
REMOTECMONREQUIRED, use #GETCONFIGURATION
/REMOTECMONREQUIRED/.
The configuration information in effect for a particular user ID depend on the setting
of the REQUESTCMONUSERCONFIG option.
When a TACL process is started, the configuration information consists of default
values. The process is in the no-user-logged-on state.
If a TACL process is in the no-user-logged-on state when a LOGON command is
received and REQUESTCMONUSERCONFIG is OFF, the TACL process sends an
initial request to the CMON process for configuration information and then sends
the LOGON request.
If the CMON process does not return configuration information, then the TACL
process uses the configuration information it had for the no-user-logged-on
state.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-103
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
If the CMON process does return the configuration information, then the TACL
process uses this information.
If the CMON process does not return the configuration information, then the
TACL process uses the information it had for the no-user-logged-on state.
If the CMON process does return the configuration information, then the TACL
process uses this information. The CMON process has had the opportunity to
change the configuration information that it wants associated with the user ID.
The TACL process uses the configuration information it was using for the
previous user ID.
If the CMON process does not return configuration information, the TACL
process uses the configuration information it was using for the previous user
ID.
If the CMON process does return information, then the TACL process uses this
information. The CMON process has had the opportunity to change the
configuration information that it wants associated with the user ID.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-104
U T IL S :T A C L C om m an d s a nd F u nctio ns
LO G O N C o m m a n d
U T IL S :T A C L C om m an d s a nd F u nctio ns
Z^DATA(0)
BYTE(0:111)
LO G O N C o m m a n d
\PRUNE.$MP:150608489
Examples
1. User SOFTWARE.JANE, whose password is STAR, can log on interactively by
entering:
TACL 1> LOGON SOFTWARE.JANE,STAR
2. Using the blind logon feature, SOFTWARE.JANE can log on in this sequence:
TACL 1> LOGON SOFTWARE.JANE
Password:
At the Password: prompt, she enters her password, which does not appear on
the screen. TACL displays a logon message, followed by its prompt, consisting of a
history number, a greater-than symbol, and a space (1>). SOFTWARE.JANE can
now enter her next command.
3. This example shows how to log on as another user and retain all your current
settings. The user MANUF.FRED has logged on and is using the system. Next he
logs on with the user name MANUF.MABEL (he must know her password); this
LOGON command implicitly logs FRED off. He changes the security of one of
Mabels files, and then he logs on again with his own ID. The final logon also logs
off MANUF.MABEL:
7> LOGON MANUF.MABEL
Password:
8> FUP SECURE BIG.FILE, "NNNU"
9> LOGON MANUF.FRED
Password:
All of Freds logon defaults remain unchanged, as well as any settings he may
have made with ASSIGN, PARAM, and SET commands.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-106
U T IL S :T A C L C om m an d s a nd F u nctio ns
_ LO N G E S T F u nctio n
_LONGEST Function
Use the _LONGEST function to obtain the length of the longest element in a list of
elements.
_LONGEST list
list
is a list of elements separated by spaces, or a variable level containing such a
list.
Result
_LONGEST returns the length of the longest element supplied in its argument.
Example
This example illustrates the use of _LONGEST to determine the length of the longest
item in a variable level:
12> PUSH do
13> SET VARIABLE do GO RUN EXECUTE
14> #OUTPUT [_LONGEST [do] ]
7
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-107
U T IL S :T A C L C om m an d s a nd F u nctio ns
_ M O N T H 3 F u nctio n
_MONTH3 Function
Use the _MONTH3 function to obtain the three-letter abbreviation for month num.
_MONTH3 num
num
is a one- or two-digit number indicating a month.
Result
_MONTH3 returns the three-letter abbreviation for the specified month.
Example
This example illustrates the use of _MONTH3 to convert the numeric representation of
a month to a three-letter textual representation:
13> #OUTPUT [_MONTH3 3]
MAR
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-108
U T IL S :T A C L C om m an d s a nd F u nctio ns
O [B E Y ] C o m m a n d
O[BEY] Command
Use the OBEY command to execute a series of TACL commands or built-in functions
contained in a file.
O[BEY] command-file
command-file
is either the name of an existing disk file that contains TACL commands or built-in
functions, or the name of a running process.
Considerations
If command-file is the name of an existing file, TACL opens the file in read-only
mode and interprets each logical line in the file as a command or command
sequence to be executed.
If command-file is the name of an existing process, TACL performs a WRITEREAD
operation, sending the process a prompt of the form OBEY> and waiting for the
process to reply. The response, presumably a command or command sequence
for TACL to execute, can contain as many as 239 characters. TACL continues to
prompt and accept replies until the process sends back an end-of- file character or
terminates.
The OBEY command:
TACL does not check the file type or contents before trying to interpret the file. If
the file does not contain TACL commands, the TACL process tries to interpret each
line and returns errors.
You cannot include TACL directives (such as ?TACL or ?FORMAT) in an OBEY
command file. For example, the OBEY command returns an error when
interpreting a file that starts with a ?TACL MACRO directive.
You can stop the execution of commands in an OBEY file by pressing the BREAK
key at the terminal where you entered the OBEY command. TACL closes the
OBEY file and prompts you for the next command. (Note, however, that you can
set the #BREAKMODE built-in variable to disable the BREAK key; in this case,
TACL ignores the BREAK key.)
Example
To execute the commands in the file ALLFILES (assuming that ALLFILES is in the
current subvolume), type:
14> OBEY allfiles
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-109
U T IL S :T A C L C om m an d s a nd F u nctio ns
OUTVAR Command
Use the OUTVAR command to display the contents of a variable without executing or
invoking it. The OUTVAR command is an alias for the #OUTPUTV built-in function.
OUTVAR [ / option [ , option ] ... / ] string
option
is an option that qualifies the write operation. Options are not permitted if variable
is of type STRUCT. Specify option as one of these:
COLUMN num
begins writing data at column num. If text in the buffer already extends beyond
the specified column, TACL outputs the buffer first and starts a new line.
FILL { SPACE | ZERO }
specifies the character (space or zero) that is to fill the unused character
positions to the right if the output is narrower than the number of columns
specified by WIDTH.
HOLD
holds the last line of the variable output in a buffer until one of these events
occurs:
U T IL S :T A C L C om m an d s a nd F u nctio ns
string
is the data to be output. It is the name of an existing variable level, text enclosed in
quotation marks, or a concatenation of such entities. The concatenation operator is
'+' (the apostrophes are required).
Considerations
If options are supplied, the options are applied to each line of the variable as
though you had called the #OUTPUT built-in with the same options for each line of
the variable. In particular, the last line of a variable is the only one that the HOLD
option really applies to because each line forces output of any previous line.
OUTVAR with the HOLD option is useful for constructing lines to be output piece
by piece. For example, when you invoke this macro file, called BUNCHUP:
?TACL MACRO
#PUSH part
#SET part All
OUTVAR /HOLD/ part
#SET part together
OUTVAR /HOLD/ part
#SET part now
OUTVAR part
the text all comes out on one line, as follows:
13> BUNCHUP
Alltogethernow
OUTVAR does not show redefinitions unless the argument itself is one.
If #OUTFORMAT is set to PRETTY, you can control output spacing by the use of
tilde-underscore (~_) metacharacters in the data to be displayed by OUTVAR.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-111
U T IL S :T A C L C om m an d s a nd F u nctio ns
Example
This example illustrates the use of OUTVAR to display the contents of a variable. First,
define a variable name vara:
15> [#DEF vara MACRO |BODY|
15> #OUTPUT [#FILEINFO / EXISTENCE / tempfile ]
15> ]
At this point, if you type vara, TACL returns 0 (false) as the result of vara if TEMPFILE
does not exist and -1 (true) if it does exist.
16> vara
0
If you now enter the OUTVAR command for the variable vara, you see the actual
contents of vara:
17> OUTVAR vara
#OUTPUT [#FILEINFO / EXISTENCE / tempfile ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-112
U T IL S :T A C L C om m an d s a nd F u nctio ns
PARAM Command
Use the PARAM command to create a parameter and give it a value or to display all
current parameters and their values.
PARAM [ param-name param-value
[ , param-name param-value ] ... ]
param-name
is a user-defined parameter name to be assigned a value. param-name can consist
of 1 to 31 alphanumeric, circumflex (^), and/or hyphen (-) characters.
param-value
is the value assigned to param-name.
Considerations
Entering PARAM with no arguments displays the names and values of all currently
defined parameters.
Comments and leading and trailing spaces are deleted in param-value.
TACL stores the values of parameters assigned by the PARAM command and
sends the values to processes that request parameter values when the processes
are started. The interpretation of parameter values is made by the processes that
request them.
To delete existing parameters, use the CLEAR command.
All parameters are deleted when you use the LOGOFF command. Parameters and
their values are retained, however, if you enter a LOGON command without
logging off first.
If you start a new TACL process from your existing TACL process, the new TACL
process does not inherit existing PARAM values.
When a backup TACL process takes over, TACL clears all PARAMs.
TACL reserves 1024 bytes of internal storage for parameters and their values. The
number and length of parameters in effect are limited by this storage area.
From a TACL macro or routine, use #PARAM to display a list of all parameters or
the value of a specified parameter.
The same set of PARAM attributes can be configured for a generic process
through SCF. For the syntax, see the SCF Reference Manual for the Kernel
Subsystem.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-113
U T IL S :T A C L C om m an d s a nd F u nctio ns
Example
To assign the value ON to the parameter TRACE:
19> PARAM TRACE ON
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-114
U T IL S :T A C L C om m an d s a nd F u nctio ns
P A S S W O R D P ro gram
PASSWORD Program
Use the PASSWORD program to create, change, or delete your password. (Passwords
are optional and might not be required on your system.)
PASSWORD [ / run-option [ , run-option ] ... / ][ password ]
run-option
is any of the options described in the RUN[D|V] Command on page 156.
password
is the new password that you must enter when you log on. If you omit password,
your current password is deleted and no password is required to log on with your
user name. A password can include from one to eight characters, except for
spaces, commas, and null characters. Lowercase letters are not converted to
uppercase. Do not end the password with an ampersand (&) character unless you
intend to continue the password on the next line.
Considerations
Example
If you are user 8,44, you can give yourself the password schubert (all lowercase) by
entering:
14> PASSWORD schubert
THE PASSWORD FOR USER (008,044) HAS BEEN CHANGED.
You must now enter this password whenever you log on.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-115
U T IL S :T A C L C om m an d s a nd F u nctio ns
PAUSE Command
You can run more one or more processes simultaneously from within your TACL
process. Use the PAUSE command to cause TACL to wait for prompting from-or
completion of-another process.
PAUSE [ [\node-name.]{$process-name | cpu,pin } ]
\node-name
is the name of the system where the process identified by $process-name or
cpu,pin is running. If you omit \node-name, the current default system is used.
$process-name
is the name of a process for which TACL is to pause. TACL does not prompt for
commands until it receives a process deletion message from that process.
cpu,pin
is the CPU number and process identification number of a process for which TACL
is to pause. TACL does not prompt for commands until it receives a process
deletion message from that process.
Considerations
PAUSE with no parameters causes TACL to pause for the last process started from
the current TACL, or the process for which TACL last paused, if that process is still
running.
If the process is interactive, you can exit the process and regain control of your
terminal by pressing the BREAK key.
When you enter a PAUSE command, the current TACL process stops prompting
for commands, allowing the specified process (or the default process) to gain
control of your terminal if it needs to use it for communication. When the other
process finishes, or is deleted, the operating system sends a process deletion
message to TACL. When TACL regains control of your terminal, it resumes
prompting.
Assume, for example, that another process controls your terminal, and you press
the BREAK key to regain control of the terminal. To return control to that other
process, enter PAUSE. TACL regains control of your terminal after that other
process finishes or is deleted.
To list the processes that are currently running on your terminal, use the STATUS *,
TERM command. If a process has a name, you can include its cpu,pin in a PPD
command and obtain its $process-name.
You can use the WAKEUP command to specify the action TACL takes when it
receives a process deletion message.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-116
U T IL S :T A C L C om m an d s a nd F u nctio ns
If WAKEUP is set to ON, TACL regains control of the terminal when any
process started from it is deleted.
If WAKEUP is set to OFF (the default setting), TACL regains control of the
terminal when the process specified in the PAUSE command is deleted. If no
process was specified in the PAUSE command, TACL regains control of the
terminal when the last process started from it is deleted.
If you enter PAUSE with no parameters when the most recent process started from
the current TACL has already been deleted, or if you specify a process that the
current TACL did not create, TACL waits forever (no prompt appears on the
screen) unless you press the BREAK key or TACL receives a wake message,
indicating that a process was deleted.
You can enter the PAUSE command, without any parameters, even when you are
logged off.
Examples
This example illustrates how to use the BREAK key to temporarily leave a process,
such as EDIT, and return control of your terminal to TACL. After checking the status of
the EDIT process, the user returns to the EDIT process and terminates the EDIT
process:
11>EDIT FILE2
TEXT EDITOR - T9601B30 - (08MAR87)
*
(BREAK pressed)
12> STATUS *,TERM
Process Pri PFR %WT Userid Program file Hometerm
5,49 120 R 000 8,230 $SYSTEM.SYS01.TACL $TE0.#A
5,55 119 000 8,230 $SYSTEM.SYSTEM.EDIT $TE0.#A
13> PAUSE
*EXIT
14> !STA
14> STATUS *,TERM
Process Pri PFR %WT Userid Program file Hometerm
5,49 120 R 000 8,230 $SYSTEM.SYS01.TACL $TE0.#A
The asterisk prompt (*) indicates that EDIT has control of the terminal. Pressing the
BREAK key returns control of the terminal to TACL. When you enter PAUSE, the EDIT
prompt reappears.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-117
U T IL S :T A C L C om m an d s a nd F u nctio ns
PMSEARCH Command
Use the PMSEARCH command to define the list of subvolumes that TACL is to search
to find program and macro files in response to an implied RUN command.
PMSEARCH subvol-spec [ [,] subvol-spec ] ...
subvol-spec
specifies a subvolume to be searched. subvol-spec takes one of these forms:
[\node-name.][$volume.] subvol
is a syntactically correct name of an existing subvolume. If you omit \nodename or $volume, the current default system or volume is assumed.
#DEFAULTS
is a TACL keyword that, in this specific context, represents the default volume
and subvolume in use at the time you issue an implied RUN command.
Considerations
VOLUME $OLD.HOME
PMSEARCH $SYSTEM.SYSTEM #DEFAULTS [#DEFAULTS]
VOLUME $NEW.PLACE
EDIT FRED
#DEFAULTS is a TACL keyword that, in this specific context, represents the default
volume and subvolume. [#DEFAULTS] represents the defaults at the time the
search list is created; #DEFAULTS represents the defaults at the time the search
list is accessed to find a program or macro to run.
That is, [#DEFAULTS] invokes the keyword when the PMSEARCH command is
executed, returning the current default volume and subvolume names and
including them in the search list. #DEFAULTS is simply the keyword itself, which
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-118
U T IL S :T A C L C om m an d s a nd F u nctio ns
PMSEARCH places in the search list intact; it is invoked later when an implied
RUN command is executed, causing TACL to access the list.
The PMSEARCH command in the preceding example causes the program/macro
search list to contain:
$SYSTEM.SYSTEM #DEFAULTS $OLD.HOME
At that time, #DEFAULTS also represents $OLD.HOME. The next VOLUME
command changes the current default volume and subvolume; #DEFAULTS now
represents $NEW.PLACE. The implied RUN command causes TACL to search
$SYSTEM.SYSTEM, then $NEW.PLACE, and finally $OLD.HOME for the file
EDIT.
TACL invokes variables in preference to running programs. If, for example, you
issue an implied RUN command using a name that identifies both a variable
containing a TACL routine and a file containing an executable program, TACL
executes the routine instead of the program.
If you plan to run any system utilities that have duplicate names in other
subvolumes in your list, place $SYSTEM.SYSTEM first in your search list.
To see the contents of the program and macro search list, use the ENV Command
on page 8-60 or the #PMSEARCHLIST Built-In Variable on page 9-285.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-119
U T IL S :T A C L C om m an d s a nd F u nctio ns
PM SG Com m and
PMSG Command
Use the PMSG (process message) command to control logging of creation and
deletion messages about processes you create with the RUN command.
PMSG { ON | OFF }
ON
specifies that whenever a process started by the current TACL process is created
or deleted, a message is sent to the TACL OUT file (usually the home terminal).
OFF
specifies that process creation and deletion messages are not to be displayed.
(OFF is the default setting.)
The form of process creation messages is:
PID: [\node-name.]{$process-name | cpu,pin } file-name
\node-name
is the name of the system where the process (represented by $processname or by cpu,pin) is created.
$process-name
is the process name of the newly created process.
cpu,pin
is the CPU number and process number of the new process.
file-name
is the file name of the new process.
The forms of process deletion messages are:
STOPPED: [\node-name.]{$process-name | cpu,pin }
ABENDED: [\node-name.]{$process-name | cpu,pin }
\node-name
is the name of the system in which the process stopped or abnormally ended.
$process-name
is the name of the process that is to be deleted.
cpu,pin
is the CPU number and process number of the process that is to be deleted.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-120
U T IL S :T A C L C om m an d s a nd F u nctio ns
PM SG Com m and
Each process deletion message is followed by a CPU time-usage message on the next
line. The form of CPU time-usage messages is:
CPU TIME: hh:mm:ss.fff
hh
is the number of hours since the process started.
mm
is the number of minutes past the number of hours since the process started.
ss
is the number of seconds past the number of hours and minutes since the
process started.
ff
is the number of fractions of a second past the number of hours, minutes, and
seconds since the process started.
Considerations
Example
This example shows the type of information you receive when you enter the PMSG ON
command:
21> PMSG ON
22> EDIT
PID: 08,62
TEXT EDITOR - ...
*
***
*exit
STOPPED: 08,62
CPU TIME 0:00:00.019
The command at history number 21 turns on process messages. The command at
number 22 starts an EDIT process; TACL displays the cpu,pin of the process as EDIT
signs on. When you exit from the EDIT process, TACL displays a process-deletion
message.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-121
U T IL S :T A C L C om m an d s a nd F u nctio ns
PO P Com m and
POP Command
Use the POP command to delete the top-level definition of a variable. The POP
command is an alias for the #POP built-in function.
POP variable [ [,] variable ] ...
variable
is the name of an existing variable or the name of a built-in variable.
Considerations
If the top level is the only level, the POP command deletes the variable, except for
built-in variables. Trying to pop a variable that has not been pushed produces an
Expecting an existing variable message. Trying to pop the last level of a built-in
variable produces a wasnt pushed message.
When TACL encounters an #UNFRAME, it performs an implicit POP for every
PUSH (or #PUSH) that was done since the most recent #FRAME was issued.
TACL performs an implicit #POP #IN when #INPUT /UNTIL EOF/ or #INPUTV
/UNTIL EOF/ is used.
If TACL encounters an error, it performs an implicit #POP #OUT.
Do not try to pop the root directory (:). If you try this, TACL returns:
*ERROR* Cannot push or pop the root segment's root.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-122
U T IL S :T A C L C om m an d s a nd F u nctio ns
P O S T D U M P U tility
POSTDUMP Utility
The POSTDUMP utility enables explicit postdump processing of an existing full dump
file to produce an extracted dump file. It is provided for processing an existing full
dump produced by either the TNet dump method or the PARALLEL dump method. You
can use the FULL option of RCVDUMP to do a full dump, reload the halted processor,
and then explicitly run the POSTDUMP utility to create an extracted dump so that the
processor can be reloaded slightly sooner by skipping the implicit postdump
processing step.
The POSTDUMP utility does not need to be licensed because it is allowed to run under
any user ID.
POSTDUMP <in file> [ < options > ]
<in file>
is the name of an existing dump file used for input.
<options>
The format of options is:
OUT <out file>, [+]PIN { ALL | <pin list> },
ALL_PAGES, [-]DP2_CACHE, [-]DP2_SHARED,
[-]IMPLICIT_DLLS, [-]LOCKED, [-]OTHER,
[-]SYS_LIBRARY, [-]SYS_PROCESS, [-]SYSTEM
OUT <out file>
specifies the name of the extracted dump file to be created. The default
value is <in file> name suffixed with 'P', removing the third character, if
necessary, to fit the resulting name within eight characters.
[+]PIN { ALL | <pin list> }
specifies the sponsor pin(s) for which all (except free) pages are to be
included in the extracted dump. Default is processes related to the
processor halt.
ALL_PAGES
includes all (except free) pages for all (valid) pins.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-123
U T IL S :T A C L C om m an d s a nd F u nctio ns
P O S T D U M P U tility
[-]DP2_CACHE
Exclude | Include DP2 cache pages.
[-]DP2_SHARED
Exclude | Include DP2 shared segment pages.
[-]IMPLICIT_DLLS
Exclude | Include implicit DLL pages.
[-]LOCKED
Exclude | Include locked pages.
[-]OTHER
Exclude | Include possibly unclassified pages.
[-]SYS_LIBRARY
Exclude | Include system/public library pages.
[-]SYS_PROCESS
Exclude | Include sysgenned process pages.
[-]SYSTEM
Exclude | Include KSEG0/VKSEG64 pages.
Considerations
HP recommends not specifying any of the POSTDUMP options other than OUT (to
specifically name the output file) because the default page selection algorithm is
the same as that used with the implicit postdump processing by RCVDUMP and is
typically the best option.
The POSTDUMP utility is provided to process an existing full dump produced by
RCVDUMP using either the TNet dump method or the PARALLEL dump method. It
will also accept as input an existing extracted dump or an existing full dump
produced by the ONLINE dump method.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-124
U T IL S :T A C L C om m an d s a nd F u nctio ns
P O S T D U M P U tility
Examples
To process a full dump file CPU01 and create an extracted dump CPU01P, run the
following command:
10> POSTDUMP CPU01
Note. Whether installed by default or explicitly installed, the POSTDUMP utility can be used to
produce an extracted dump from a full dump of any NS-series processor that was running the
H06.13 RVU or later, or from a full dump of any HP Integrity NonStop BladeSystems (which
runs a J-series RVU).
The POSTDUMP utility can be run on such a system that was running the H06.13 RVU or later
to process a full dump file from any other NS-series processor or a full dump file from any
NonStop BladeSystems. The POSTDUMP utility does not rely on any of the other files
(RCVDUMP, ONLINDMP, ZDMPDLL).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-125
U T IL S :T A C L C om m an d s a nd F u nctio ns
PPD Command
Use the PPD (process-pair directory) command to display the names, cpu,pin
designations, and ancestors of one or more processes in the destination control table
(DCT). The PPD command is an alias for the #XPPD built-in function.
PPD [ / OUT list-file / ]
[ [ \node-name] [.{ $process-name | cpu,pin | * } ] ...]
OUT list-file
specifies a device, or a sequential file accessible to the sequential I/O (SIO) facility,
that is to receive the output from PPD. If you omit this option, TACL writes the
listing to its current OUT file.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
\node-name
is the system where the process resides.
$process-name
is the name of the process or process pair.
cpu,pin
is the CPU number and process identification number of the process.
*
displays information about all processes, including I/O processes. (This applies to
D-series or later systems only.)
Considerations
If you do not specify a process ($process-name or cpu,pin), PPD lists all the
current entries in the process-pair directory of the specified system. If you omit the
node name, the default system is assumed.
If you specify more than one process, PPD lists information for each process.
The PPD command displays information as shown:
Name Primary Backup Ancestor
pname pcpu bcpu aid
pname pcpu bcpu aid
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-126
U T IL S :T A C L C om m an d s a nd F u nctio ns
pname
is the name of the process. The name $Z000 identifies the initial process that
was started when the system was cold loaded from disk.
pcpu
is the CPU number and process number of the primary process in a process
pair, or of the specified process only if it is not a member of a pair.
bcpu
is the CPU number and process number of the backup process in a process
pair. If backup is not displayed, the process has no backup.
aid
is the identity of the ancestor process; that is, the process that created the
process listed under Name. If the ancestor is a named process, this field lists
its name; otherwise, this field contains a CPU number and process number. If
the ancestor process node is different from the specified or default node, then
TACL displays the node name. The initial process that was started when the
system was cold loaded from disk has no entry in this field.
There can be three states of an ancestor: AVAILABLE, UNAVAILABLE, and
DEFUNCT.
When we run a process from one system to another, the ancestor of the
process becomes UNAVAILABLE if they are disconnected manually.
If you include \ node-name in your PPD command, the name of the system is
displayed at the beginning of the command listing.
The DCT lists only named processes. To name a process that you start with a RUN
command, include the NAME parameter in your command. (For more information
about starting and naming processes, see the description of the RUN[D|V]
Command on page 8-156.)
The DCT lists named processes that do not have backups as well as named
process pairs.
Examples
You can get a listing of all entries in the DCT and send it to the file PROCESS.PAIR by
entering:
14> PPD / OUT PROCESS.PAIR /
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-127
U T IL S :T A C L C om m an d s a nd F u nctio ns
To view the entry in the DCT for the process $WOW, enter:
15> PPD $WOW
Name Primary Backup Ancestor
$WOW 04,054 05,009 $Z000
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-128
U T IL S :T A C L C om m an d s a nd F u nctio ns
PU RG E Com m and
PURGE Command
Use the PURGE command to delete one or more disk files.
PURGE [ / option / ]
file-name-template [ , file-name-template ... ]
option
qualifies the purge operation. Specify option as one of these:
CONFIRM
specifies that TACL is to prompt for confirmation for each file, specified by
name or by matching a template, before purging the file.
NOCONFIRM
specifies that TACL is to purge the file without requesting confirmation. This
option is provided primarily for programmatic applications that do not need
confirmation of the purge operation.
file-name-template
is a file name or partial file name with wild-card characters. For more information
about file-name templates, see Section 2, Lexical Elements.
Considerations
These considerations apply to the PURGE command:
When you use the PURGE command to delete a disk file, the entry for the file is
deleted from the file directory in the volume where it resides, and any space
previously allocated to that file is made available to other files. Data in the file is not
physically deleted from the disk unless you specified the FUP CLEARONPURGE
option when you created the file. Files that are physically deleted are overwritten
with zeros. For information about the CLEARONPURGE option, see the File Utility
Program (FUP) Reference Manual.
You can purge a file only if it is not currently open; in addition, you must have purge
access to the file. See the description of the DEFAULT Program on page 8-53 for
information about file-access restrictions.
If you try to use the PURGE command to delete a file that is being audited by the
TMF subsystem the attempt fails if there are pending transaction-mode records or
file locks; file-system error 12 (file in use) is returned. The purge is successful,
however, if the audited file is inactive.
These considerations apply to the use of the CONFIRM and NOCONFIRM options:
If you specify a file name with no wild-card characters and do not include
CONFIRM or NOCONFIRM, TACL does not display a confirm prompt.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-129
U T IL S :T A C L C om m an d s a nd F u nctio ns
PU RG E Com m and
If you specify a file-name template with wild-card characters and do not include
CONFIRM or NOCONFIRM, TACL confirms only the template (not individual file
names) before purging all files that match the template.
CONFIRM and NOCONFIRM are mutually exclusive.
Examples
If you have purge access to the files OCT and NOV (in your current default system,
volume, and subvolume) and to the file $RECORDS.DUE.PAST, you can purge all of
them by entering:
14> PURGE OCT, NOV, $RECORDS.DUE.PAST
$DATA.LNP.OCT Purged
$DATA.LNP.NOV Purged
$RECORDS.DUE.PAST Purged
15>
This command requests confirmation of the PURGE operation:
15> PURGE /CONFIRM/ abc
PURGE $VOL1.SV.ABC (Y/[N])?
If you respond with Y, TACL purges the file. Any other response is treated as N.
This command confirms the file-name template before purging matching files:
16> PURGE abc*
PURGE $VOL1.SV.ABC* (y/[n])?
This command confirms each file that matches a file-name template before purging
matching files:
17> PURGE /CONFIRM/ abc*
PURGE $VOL1.SV.ABC1 (y/[n])? y
$VOL1.SV.ABC2 Purged
PURGE $VOL1.SV.ABC2 (y/[n])? n
18>
This macro alters PURGE confirmation behavior so that TACL confirms purge
operations:
?SECTION purgec MACRO
PURGE /CONFIRM/ %*%
This macro alters PURGE confirmation behavior so that TACL does not confirm purge
operations:
?SECTION purgen MACRO
PURGE /NOCONFIRM/ %*%
To use either of the preceding macros, load the associated file and type PURGEC or
PURGEN, respectively.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-130
U T IL S :T A C L C om m an d s a nd F u nctio ns
PUSH Command
Use the PUSH command to create a new top level for one or more variables or built-in
variables. The PUSH command is an alias for the #PUSH built-in function.
PUSH variable [ [,] variable ] ...
variable
is a valid variable or a built-in variable name.
Considerations
For existing variables that are not built-in variables, PUSH creates an empty top
level of type TEXT.
For built-in variables, PUSH creates a new top-level definition, copying the old top
level to the new one (top-level and second-level definitions are now the same).
If the variable does not exist, PUSH registers the name of the variable, but does
not allocate space until you use SET VARIABLE or a similar command or built-in
function to actually place data into the variable. As a result, you must perform a
SET VARIABLE or related operation prior to using the variable in an #IF call or
other command or function that tests the value of the variable.
The default type for variables is TEXT. To change this type, use the SET
VARIABLE command.
Do not try to PUSH the root directory (:). If you try this, TACL returns *ERROR*
Cannot push or pop the root segment's root. In addition, to avoid
losing standard functionality from your TACL environment, do not PUSH the
directories supplied as part of a software RVU (such as UTILS).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-131
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-132
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-133
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
Caution. This command should be used only as part of a documented processor dumping and
recovery procedure. See the sections Processors: Monitoring and Recovery and Starting and
Stopping the System in the NonStop S-Series Operations Guide or the Integrity NonStop NSSeries Operations Guide.
If a memory dump is requested as part of a recovery procedure, for processors with more than
2 gigabytes of memory, use the HP Tandem Failure Data System (TFDS) memory dump facility
to ensure that the dump occurs in a timely fashion. Otherwise, use either RCVDUMP or the
TFDS facility. TFDS must be configured on the system before the halt occurs.
H-Series Syntax
RCVDUMP
<filename>, cpuNum [, SLICE <sliceId>]
[, START <startAddress>][, END <endAddress>]
[, [ONLINE | PARALLEL] [, FULL] ]
filename
is the name of the disk file to which the dump is to be written.
cpuNum
is the number of the logical processor from which a processor element is to be
dumped. Specify cpuNum as an integer in the range from 0 through 15.
SLICE <sliceId>
is the identification of the slice from which the processor element is to be dumped.
Valid values are A or B or C or ALL. The default is ALL. Note that ALL may not
be used with the parallel method of dumping.
START n...
is the byte address where the dump will start. The default value is 0.
END n...
is the byte address where the dump will stop. Using a value of -1 is the same as
specifying the end of memory. The default value is -1.
ONLINE
If this option is specified, the dump of a processor can be taken while it is running
and only a full dump file (excluding free memory) is created. You may use either
PARALLEL or ONLINE but not both.
PARALLEL
If this option is specified, the dump of a single processor element can be taken
while the other PEs in that logical processor are reloaded and continue normal
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-134
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
operations. By default, both the full dump and extracted dump files are created.
You may use either PARALLEL or ONLINE but not both.
Note. When neither ONLINE nor PARALLEL is specified:
FULL
Specifies that only a full dump is to be created and not an extracted dump.
Note. This option is supported only on systems running J06.03 and later J-series RVUs
and H06.14 and later H-series RVUs.
G-Series Syntax
RCVDUMP [ / run-option [ , run-option ] ... / ]
dump-file , cpu , [ fabric, param [ , param ] ]
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
dump-file
is the name of the disk file to which the dump is to be written.
cpu
is the number of the processor that is to be dumped. Specify cpu as an integer in
the range from 0 through 15.
fabric
specifies the ServerNet fabric to be used for the dump operation. The default fabric
is the X fabric. Possible values are:
X = X fabric
Y = Y fabric
param
is one or more of these parameters:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-135
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
START n...
is the byte address where the dump will start. The default value is 0.
END n...
is the byte address where the dump will stop. Using a value of -1 is the same
as specifying the end of memory. The default value is -1.
ONLINE
If this option is specified, a dump can be taken of a processor while it is
running. Only memory pages are included in this type of dump. No registers,
translation lookaside buffers (TLB) or caches are dumped. All other parameters
are ignored, including fabric.
RESET
If this option is specified, a soft reset is issued to the processor being dumped.
This option is necessary if the processor has experienced a hardware error
freeze instead of a halt.
Note. The PRIME and NOPRIME parameters do not have any effect on how the
RCVDUMP command operates. They are therefore no longer described in the RCVDUMP
command description.
D-Series Syntax
RCVDUMP [ / run-option [ , run-option ] ... / ]
dump-file , cpu , [ bus, param [ , param ] ]
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
dump-file
is the name of the disk file to which the dump is to be written.
cpu
is the number of the processor that is to be dumped. Specify cpu as an integer in
the range from 0 to 15, inclusive. This processor must be primed for a memory bus
dump before you attempt the dump.
bus
specifies the bus to be used for the dump. The default bus is the X bus. Possible
values are:
0 = X bus
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-136
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
1 = Y bus
param
is either one of these parameters:
FULL
specifies that the entire physical memory is to be dumped. FULL is the default
for a processor if the size of physical memory is less than or equal to sixteen
megabytes. This option is ignored if the processor is not a VLX.
PARTIAL
specifies that only those pages of physical memory that are mapped in the
page table cache are to be dumped. PARTIAL is the default for a processor
with more than sixteen megabytes of physical memory. This option is ignored if
the processor is not a VLX.
Note. The PRIME and NOPRIME parameters do not have any effect on how the
RCVDUMP command operates. They are therefore no longer described in the RCVDUMP
command description.
Considerations
If the file dump-file does not already exist, a file with that name is created.
D-series: If dump-file exists, it must be empty (its end-of-file pointer must be set
to zero). If dump-file is not empty, RCVDUMP aborts. Also, if the empty dumpfile exists, but its primary and secondary extent sizes are too small to contain
the entire dump, the file is purged, and a new dump-file with extent sizes of
sufficient size is created.
H-series or G-series: If the file already exists RCVDUMP prompts the user to
specify whether it can overwrite the file. If the answer is ' no', RCVDUMP aborts.
Otherwise it overwrites the existing file and continues.
Any dump file created with G06.16 RVU or later has a file code of 145. Any dump
file created with an earlier RVU has a file code of 144. Any dump file created with
any J-series RVU or any H-series RVU has a file code of 148.
In H-series, if the system is not a duplex or triplex configuration, or if the ONLINE
or PARALLEL method is not specified, the default method is to use the TNet dump
method in conjunction with Halted State Services running in the halted processor to
be dumped. For more information on Halted State Services, contact your local HP
service provider.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-137
U T IL S :T A C L C om m an d s a nd F u nctio ns
R C V D U M P P ro g ra m (S u p er-G ro up o r S u pe r ID
O nly)
Example
For G-series RVUs, if you have the super-group user ID, you can initiate a dump from
processor 6 of your system over the X fabric and send the dump to file
$SYSTEM.DUMP.DUMP1 by entering:
14> RCVDUMP $SYSTEM.DUMP.DUMP1 , 6 , X
CPU 06 HAS BEEN DUMPED TO $SYSTEM.DUMP.DUMP1.
For H-series RVUs, if you have the super-group user ID, you can initiate a dump from
the processor element on slice A that belongs to logical processor 3, while the other
processor elements of logical processor 3 continue normal operations:
10> RCVDUMP $SYSTEM.DUMP.DUMP1 , 3 , SLICE A , PARALLEL
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-138
U T IL S :T A C L C om m an d s a nd F u nctio ns
R E C E IV E D U M P C o m m a n d (S u pe r-G ro up O nly)
G-Series Syntax
RECEIVEDUMP / OUT dump-file / cpu , fabric
[ , param [ , param ] ]
dump-file
is the name of the disk file to which the dump is to be written.
cpu
is the number of the processor that is to be dumped. Specify cpu as an integer in
the range from 0 through 15.
fabric
specifies the ServerNet fabric to be used for the dump operation. The default fabric
is the X fabric. Possible values are:
0 = X fabric
1 = Y fabric
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-139
U T IL S :T A C L C om m an d s a nd F u nctio ns
R E C E IV E D U M P C o m m a n d (S u pe r-G ro up O nly)
param
is one or both of these parameters:
ONLINE
If this option is specified, a dump can be taken of a processor while it is
running. Only memory pages are included in this type of dump. No registers,
translation lookaside buffers (TLB) or caches are dumped. All other parameters
are ignored, including fabric.
RESET
If this option is specified, a soft reset is issued to the processor being dumped.
This option is necessary if the processor has experienced a hardware error
freeze instead of a halt.
Note. The PRIME and NOPRIME parameters do not have any effect on how the
RCVDUMP command operates. They are therefore no longer described in the RCVDUMP
command description.
D-Series Syntax
RECEIVEDUMP / OUT dump-file / cpu , bus
[ , param [ , param ] ]
dump-file
is the name of the disk file to which the dump is to be written.
cpu
is the number of the processor that is to be dumped. Specify cpu as an integer in
the range from 0 to 15, inclusive. This processor must be primed for a memory bus
dump before you attempt the dump.
bus
specifies the bus to be used for the dump. The default bus is the X bus. Possible
values are:
0 = X bus
1 = Y bus
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-140
U T IL S :T A C L C om m an d s a nd F u nctio ns
R E C E IV E D U M P C o m m a n d (S u pe r-G ro up O nly)
param
is either one of these parameters:
FULL
specifies that the entire physical memory is to be dumped. FULL is the default
for a processor if the size of physical memory is less than or equal to sixteen
megabytes. This option is ignored if the processor is not a VLX.
PARTIAL
specifies that only those pages of physical memory that are mapped in the
page table cache are to be dumped. PARTIAL is the default for a processor
with more than sixteen megabytes of physical memory. This option is ignored if
the processor is not a VLX.
Note. The PRIME and NOPRIME parameters do not have any effect on how the
RCVDUMP command operates. They are therefore no longer described in the RCVDUMP
command description.
Considerations
If the file dump-file does not exist when you enter the RECEIVEDUMP
command, a new file named dump-file is created.
D-series: If dump-file exists, it must be empty; that is, its end-of-file (EOF)
pointer must be set to zero. If dump-file is not empty, it is not overwritten:
RECEIVEDUMP returns an error message. Also, if the empty dump-file exists,
but its primary and secondary extent sizes are too small to contain the entire dump,
the file is purged and a new dump-file with extent sizes of sufficient size is
created.
G-Series: If the file already exists RCVDUMP prompts the user to specify whether
it can overwrite the file. If the answer is ' no', RCVDUMP aborts. Otherwise it
overwrites the existing file and continues.
Any dump file created with RVU G06.16 or later has a file code of 145. Any dump
file created with an earlier RVU has a file code of 144.
Example
For G-series RVUs, if you have a super-group user ID, you can initiate a dump from
processor 4 of your system over the Y fabric and send the dump to file
$SYSTEM.DUMP.DUMP2 by entering:
74> RECEIVEDUMP /OUT $SYSTEM.DUMP.DUMP2/ 4,1
CPU 04 HAS BEEN DUMPED TO $SYSTEM.DUMP.DUMP2.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-141
U T IL S :T A C L C om m an d s a nd F u nctio ns
H-Series Syntax
RELOAD [ / run-option [ , run-option ] ... / ]
cpu-set [; cpu-set ] ...
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
cpu-set
is a set of processors (and associated options) to be reloaded. Specify cpu-set
as:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-142
U T IL S :T A C L C om m an d s a nd F u nctio ns
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-143
U T IL S :T A C L C om m an d s a nd F u nctio ns
OMITSLICE [A|B|C]
The PE on the selected slice will not be reloaded when other PEs in that
logical processor are reloaded. If you do not provide an argument (A or B
or C) the system will choose a slice to omit.
<$volume [.sysnn.osdir]>
specifies a volume other than $SYSTEM where the operating system
image (sysnn.osdir) to be used for reloading the processor is located.
This specification could take the form of $volume or
$volume.sysnn.osdir or sysnn.osdir or osdir depending on your
requirements.
*
specifies that all failed processors should be reloaded.
A help screen is displayed if you enter RELOAD with no parameters and no IN filename.
G-Series Syntax
RELOAD [ / run-option [ , run-option ] ... / ]
cpu-set [; cpu-set ] ...
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
cpu-set
is a set of processors (and associated options) to be reloaded. Specify cpu-set
as:
{ cpu-range } [, option, option, ... ]
{ ( cpu-range, cpu-range, ...) }
{ * }
cpu-range
is one of these:
cpu
cpu-cpu
cpu
is the processor number, an integer from 0 through 15.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-144
U T IL S :T A C L C om m an d s a nd F u nctio ns
cpu-cpu
is two processor numbers separated by a hyphen, specifying a range of
processors. In a range specification, the first processor number must be
less than the second.
option
is one of these:
NOSWITCH
[PRIME|NOPRIME]
<fabric>
<$volume [.sysnn.osimage]>
NOSWITCH
specifies that, when a processor is reloaded, there is no default autoswitch
of controller ownership to the configured primary processor.
[PRIME|NOPRIME]
Sets up the logical processor for the reload operation.
NOPRIME is the default.
fabric
specifies whether the X fabric or Y fabric is used for the transfer of the
operating system image to the processor during the RELOAD operation.
0 = X fabric
1 = Y fabric
The default option is the X fabric.
<$volume [.sysnn.osimage]>
specifies a volume other than $SYSTEM where the operating system
image (SYSnn.OSIMAGE) to be used for reloading the processor is
located.
This specification could take the form of $volume or
$volume.sysnn.osimage or sysnn.osimage or osimage depending
on your requirements.
If a subvolume is not specified, the default subvolume in effect at the time
the RELOAD command is issued is used.
*
specifies that all failed processors should be reloaded.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-145
U T IL S :T A C L C om m an d s a nd F u nctio ns
A help screen is displayed if you enter RELOAD with no parameters and no IN filename.
D-Series Syntax
RELOAD [ / run-option [ , run-option ] ... / ]
cpu-set [; cpu-set ] ...
[ HELP ]
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
cpu-set
is a set of processors (and associated options) to be reloaded. Specify cpu-set
as:
{ cpu-range } [, option, option, ... ]
{ ( cpu-range, cpu-range, ...) }
{ * }
cpu-range
is one of these:
cpu
cpu-cpu
cpu
the processor number, an integer from 0 through 15.
cpu-cpu
two processor numbers separated by a hyphen, specifying a range of
processors. In a range specification, the first processor number must be
less than the second.
option
is one of these:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-146
U T IL S :T A C L C om m an d s a nd F u nctio ns
NOSWITCH
bus
$volume
subvolume.filename
NOSWITCH
specifies that, when a VLX, CLX, CYCLONE or NSR-L processor is
reloaded, there is no default autoswitch of controller ownership to the
configured primary processor.
bus
specifies whether the X bus or the Y bus is used for the transfer of the
operating-system image to the processor during the RELOAD operation.
0 = X bus
1 = Y bus
The default option is the X bus.
$volume
specifies a volume other than $SYSTEM where the operating system
image (SYSnn.OSIMAGE) to be used for reloading the processor is
located.
subvolume.filename
specifies a subvolume and file where the operating system image to be
used for reloading the processor is located. If subvolume is not specified,
the default subvolume in effect at the time the RELOAD command is
issued is used.
*
specifies that all failed processors should be reloaded.
HELP
displays a help screen summarizing the RELOAD command syntax and giving an
example of RELOAD. The help screen is also displayed if you enter RELOAD with
no parameters and no IN file-name.
Note. The PRIME and NOPRIME parameters do not have any effect on how the
RCVDUMP command operates. They are, therefore, no longer described in the
RCVDUMP command description.
Considerations
U T IL S :T A C L C om m an d s a nd F u nctio ns
The alternate operating-system image file (in H-series, the OS FileSet) option:
The alternate operating-system image file (in H-series, the OS FileSet) you use
must be an exact duplicate of the file being used by the processor from which the
RELOAD command is issued. All processors must be loaded with identical
operating-system images. The alternate operating-system image file (in H-series,
the OS FileSet) option is not a substitute for cold loading the system. It cannot be
used to change the operating-system image.
If an alternate operating-system image file (in H-series, the OS FileSet) is
specified, that file continues to be used by the processor into which it is loaded.
Thus, different processors can be using identical files from various locations.
In addition, if an alternate operating-system image file (in H-series, the OS FileSet)
is specified, all the files in the reloaders default SYSnn must be present in the
subvolume specified in the alternate fileset option of the RELOAD command.
G-series and D-series Only. RELOAD checks the operating-system image file to
ensure that it has the same timestamp as the operating-system image in the
processor doing the reload. If the timestamps do not match, and the volume is
already accessible (allowing the timestamp to be immediately checked), reloading
of the affected processors does not occur. If the volume is inaccessible, the
reloaded processor checks the timestamp and halts with a %4016 code if it does
not match.
You can use an IN file to enter RELOAD command parameters. The IN file can be
a disk file but not a terminal. An IN file can contain multiple lines as long as no
cpu-set is divided between lines. To start a RELOAD process using an IN file,
enter RELOAD with only the IN file-name specification. (For more information, see
the RUN[D|V] Command on page 8-156.)
When one of the two processors connected to a controller fails, the other
processor gains ownership of the controller. When a failed processor (or one that
has not been loaded) is reloaded:
U T IL S :T A C L C om m an d s a nd F u nctio ns
The procedures for dumping an entire system that is frozen are described in the
NonStop S-Series Operations Guide or the NonStop NS-Series Operations Guide.
Note. When using the CIIN file, you should include in it only those necessary commands
that are restricted to super-group use, such as SETTIME or ADDDSTTRANSITION, and
perhaps a command to start a TACL process. Any other commands can be put into system
startup files. In particular, you should not put commands to start application processes in
the CIIN file, as they can cause CPU halts or system freezes in the event of application
malfunction.
Examples
1. To reload processor 1 using the currently selected bus and to prevent switches in
device ownership, enter:
14> RELOAD 1, NOSWITCH
2. This G-series example uses the Y bus and the alternate operating system image in
the file $DATA.SYS02.OSIMAGE to reload processors 2, 4, 5, 6, and 7. The same
command then reloads all other downed CPUs using the default operating system
image and the currently selected bus:
15> RELOAD (2, 4-7) , $DATA.SYS02.OSIMAGE , 1; *
3. These H-series examples demonstrate use of the OMITSLICE option.
The first command uses a mutiple cpu-set specification, reloading all processor
elements belonging to logical processor 2 with the exception of the PE on slice A,
and the command continues to a second cpu-set specification to reload all PEs
belonging to processor 3.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-149
U T IL S :T A C L C om m an d s a nd F u nctio ns
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-150
U T IL S :T A C L C om m an d s a nd F u nctio ns
Considerations
If you omit password, your remote password for \node-name is deleted. If you
omit \node-name, all of your remote passwords are deleted
If you omit both parameters, TACL returns this prompt:
Do you really want to delete all of your remote passwords?
If you type y or yes (either uppercase. lowercase, or any combination of
uppercase and lowercase characters), password deletion occurs.
RPASSWRD also prompts first to verify that deleting your remote passwords is
what you actually intend to do.
You must establish remote passwords before you can access remote systems in a
network. To gain access to a remote system, you must have identical remote
passwords in effect on both the system where you are logged on and the remote
system.
If RPASSWRD detects a null character in a remote password, it aborts without
changing the remote password. Null characters can inadvertently be included by
entering certain control-character combinations at a terminal. See the user
documentation for your terminal for a list of control characters that might interfere
with your terminal operation.
See the Guardian Users Guide for information about the use of remote passwords
in network security.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-151
U T IL S :T A C L C om m an d s a nd F u nctio ns
Examples
1. Suppose that you are user MANUF.FRED on system \ROME, and you need
access to files on system \PARIS. First, log on to the \ROME system and establish
the remote passwords YES for the \PARIS system and OK for the \ROME system
by entering these commands:
14> REMOTEPASSWORD \PARIS, YES
THE \PARIS REMOTE PASSWORD FOR MANUF.FRED (8,44) HAS BEEN
CHANGED.
15> REMOTEPASSWORD \ROME, OK
THE \ROME REMOTE PASSWORD FOR MANUF.FRED (8,44) HAS BEEN
CHANGED.
16>
Now you must log on to the \PARIS system and use the same commands to
establish the same remote passwords. Because you do not yet have access to
\PARIS, you normally need to contact the system manager for the \PARIS system,
who logs on as a super-group user. The system manager then logs on with your
user name and enters the commands for you.
2. To delete the remote password for \PARIS from the \ROME system, log on to
\ROME and enter:
20> REMOTEPASSWORD \PARIS
THE \PARIS REMOTE PASSWORD FOR MANUF.FRED (008,044) HAS
BEEN DELETED.
21>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-152
U T IL S :T A C L C om m an d s a nd F u nctio ns
RENAME Command
Use the RENAME command to change the name of an existing disk file.
RENAME old-file-name [,] new-file-name
old-file-name
is the name of the disk file to be renamed.
new-file-name
is the new name for the file.
Considerations
You can rename a file only if it is not open with exclusive access, and you either
have purge access to the file or are logged on as a super-group user.
You can use the RENAME command to change the subvolume name of a file, but
not its volume name. Disk files that are renamed stay on the same disk volume.To
change the volume where a file resides, copy the file to a new volume with the
FUP DUP command, then delete the original file. For details, see the File Utility
Program (FUP) Reference Manual.
If you try to rename a file being audited by TMF, the attempt fails and file-system
error 80 (operation invalid) is returned.For information about TMF and the AUDIT
option, see the TMF Reference Manual.
Format 1 files, Format 2 files, and files opened with READ ONLY ACCESS can be
renamed.
Examples
1. To rename the file RECORDS.DATA to STORAGE.OLDDATA, enter:
14> RENAME RECORDS.DATA, STORAGE.OLDDAT
15>
2. To rename the file MYSTUFF in the current default subvolume to be TRASH in the
subvolume EXTRA, enter:
15> RENAME MYSTUFF, EXTRA.TRASH
16>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-153
U T IL S :T A C L C om m an d s a nd F u nctio ns
R E S E T D E F IN E C o m m a n d
{*}
attribute-name
is the name of a DEFINE attribute whose value is to be reset to its initial value. For
the syntax of attribute-name, see SET DEFINE Command on page 8-173. If you
reset a defaulted attribute, it assumes its default value. If you reset an optional
attribute, it has no value. You cannot reset a required attribute after a value has
been assigned to it.
*
resets all the attributes in the working attribute set to their initial settings. That is,
CLASS is reset to MAP, and the only CLASS MAP attribute, FILE, is reset to have
no value.
Considerations
If any error occurs on a RESET DEFINE command, the command has no effect on
the working attribute set. The DEFINE command error messages are listed and
described in Appendix B, Error Messages. Entering RESET DEFINE * is equivalent
to specifying SET DEFINE CLASS MAP.
That is, RESET DEFINE * resets CLASS to MAP (the default value), establishes
the attributes of CLASS MAP as the working attribute set, and restores each of
those attributes to its initial setting; for example:
69> RESET DEFINE *
70> SHOW DEFINE
CLASS MAP
FILE ??
Current attribute set is incomplete
Because the CLASS attribute acts as a DEFINE subtype, you should keep these
points in mind when using the RESET DEFINE command:
Attributes are reset in the order they are specified in your command.
An error occurs if you reset an attribute that is not a member of the working
attribute set (such as an attribute that is not associated with the current
CLASS).
Resetting the CLASS attribute establishes a new working attribute set of the
default CLASS (MAP); its single attribute, FILE, has no value.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-154
U T IL S :T A C L C om m an d s a nd F u nctio ns
R E S E T D E F IN E C o m m a n d
Example
This RESET DEFINE command resets the USE attribute in the current working
attribute set. Because USE is an optional attribute, it ceases to have any value.
71> SHOW DEFINE *
CLASS
VOLUME
LABELS
REELS
OWNER
FILESECT
...
USE
DEVICE
...
TAPEMODE
72> RESET DEFINE USE
73> SHOW DEFINE *
CLASS
VOLUME
LABELS
REELS
OWNER
FILESECT
...
USE
DEVICE
...
TAPEMODE
TAPE
M5436
IBM
PURCHG
002
IN
$TAPE
TAPE
M5436
IBM
PURCHG
002
$TAPE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-155
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
RUN[D|V] Command
Use the RUN command to run programs or TACL macros. You invoke the RUND or
RUNV command with the same parameters and options as the RUN command, but the
RUND command runs programs under control of the INSPECT symbolic debugger or
DEBUG, while the RUNV command runs programs under the control of the VISUAL
INSPECT symbolic debugger.
A RUN command must name an object file or TACL program file that contains the
program you want to run. You can enter RUN commands either explicitly or implicitly:
For an explicit RUN command, enter the keyword RUN (or RUND or RUNV) followed
by the name of the program file.
For an implicit RUN command, enter the name of the program file. If you omit RUN or
enter a command that TACL does not recognize, TACL assumes you are entering an
implicit run command. TACL searches for program-file in the subvolumes listed in the
#PMSEARCHLIST variable
The program DEBUG is not available for use on systems running H-series software.
The DEBUG command invokes a debugger, it can be Inspect, Native Inspect
(eInspect, which is not in the family of Inspect debuggers), or Visual Inspect.
If the INSPECT attribute is set ON anywhere (in the object file during compilation, or on
the TACL command line using the SET command), you will get a debugger in the
Inspect family (either Inspect or VI), unless of course neither of these debuggers is
available, and then you get the default debugger, eInspect. If the Inspect attribute is
OFF, you get Native Inspect (eInspect).
Inspect is invoked only for TNS accelerated/interpreted programs (never for TNS/E
native programs), while Visual Inspect can handle both of these. Native Inspect
handles only TNS/E native programs and snapshots..
[ RUN[D] ] program-file
[/ run-option [ , run-option ] ... / ]
[ param-set ]
program-file
is the name of the file containing the object program to be run. Partial file names
are expanded using the current TACL default system, volume, and subvolume
names if you enter an explicit RUN command.
run-option
is any of these:
CPU
HIGHPIN
JOBID
NAME
PRI
DEBUG
IN
LIB
NOWAIT
STATUS
DEFMODE
INLINE
MAXMAINSTACKSIZE*
OUT
SWAP
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-156
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
EXTSWAP
INSPECT
MAXNATIVEHEAPSIZE*
OUTV
TERM
GUARANTEEDSWAPSPACE*
INV
MEM
PFS
WINDOW
* These options are available when the default configuration settings of the TACL process are
changed. To change the settings, set the TACL configuration parameter CONFIGRUN to
PROCESSLAUNCH. For more information, see the #SETCONFIGURATION option, CONFIGRUN
[ PROCESSCREATE | PROCESSLAUNCH ].
CPU cpu-number
specifies the number of the processor where the process is to run. Specify
cpu-number as an integer in the range from 0 through 15. If you omit this
option, the process runs in the same processor as TACL (but if a $CMON
process exists, it might specify a processor other than that one; see the
Guardian Programmers Guide for information about $CMON).
DEBUG
causes the process to start in the debug mode. This option is not valid in a
RUND or RUNV command.
RUN program-file / DEBUG / is the same as RUND program-file.
DEFMODE { OFF | ON }
specifies the initial DEFMODE setting (controlling both enabling and
propagation of DEFINEs) for the process you are starting, and determines
which DEFINEs are propagated to the newly started process. If you do not
include the DEFMODE option, the initial DEFMODE setting for the process you
are starting is the DEFMODE setting for the current TACL. The DEFMODE
option has no effect on the DEFMODE setting for the current TACL.
If you specify DEFMODE OFF, all DEFINEs are disabled for the new process,
and no DEFINE is propagated from the current TACL to the new process.
If you specify DEFMODE ON, all DEFINEs are enabled for, and propagated to,
the new process.
EXTSWAP [ file-name ]
specifies the name of a file to be used as swap space for the default extended
data of the process. The EXTSWAP file must reside on the same node as the
program file.
For processes running with pre-D42 software RVUs, omitting this option
causes the Kernel-Managed Swap Facility (KMSF) to create the default
extended swap file on the volume specified by the SWAP volume in the
=_DEFAULTS DEFINE. If there is no SWAP volume in the =_DEFAULTS
DEFINE, the operating system chooses one. For more information about the
KMSF facility, refer to the Kernel-Managed Swap Facility (KMSF) Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-157
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
For non-native processes running with D42 or later software RVU, omitting this
option causes the Kernel-Managed Swap Facility (KMSF) to allocate swap
space for the default extended data segment of the process. For more
information about the KMSF facility, refer to the Kernel-Managed Swap Facility
(KMSF) Manual.
For native processes running with D42 or later software RVUs, the specified
file-name is ignored because these processes do not need an extended swap
file.
If you omit this option, the extended swap file is created on the volume
specified by the SWAP volume in the =_DEFAULTS DEFINE. If there is no
SWAP volume in the =_DEFAULTS DEFINE, the operating system chooses a
volume for the extended swap file.
GUARANTEEDSWAPSPACE number-of-bytes
where number-of-bytes specifies the size, in bytes, of the space that the
process reserves with the Kernel-Managed Swap Facility for swapping. For
more information on this facility, refer to the Kernel-Managed Swap Facility
(KMSF) Manual. The value provided is rounded up by operating-system
procedures to a page size boundary that is appropriate for the processor. For
more information, see the description of the Z^SPACE^GUARANTEE
parameter of the PROCESS_LAUNCH_ procedure in the Guardian Procedure
Calls Reference Manual.
Note. T h is o p tio n is a va ila b le w h e n th e d e fa ult co n figu ra tion settin g s o f the T A C L
p roce ss a re ch a ng e d . T o ch an g e the settin g s, se t th e T A C L co n fig u ra tio n p ara m ete r
C O N F IG R U N to P R O C E S S LA U N C H . F o r m o re in fo rm a tio n, se e th e
# S E T C O N F IG U R A T IO N o ptio n , C O N F IG R U N [ P R O C E S S C R E A T E |
P R O C E S S L A U N C H ] o n p a g e 9 -3 4 8 .
HIGHPIN { ON | OFF }
specifies the desired PIN range for a new process.
ON
specifies that a process will run at a high PIN if the HIGHPIN bit is enabled
in the object file (and in the library file, if any) and if a high PIN is available.
OFF
specifies that the process runs at a low PIN, regardless of any other
considerations.
The default value for HIGHPIN depends on the values of the Binder
HIGHPIN option and the HIGHPIN variable. If you start a TACL process with
HIGHPIN OFF, any processes started by the TACL process run at a low PIN by
default.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-158
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
IN [ file-name | $process-name ]
is the IN file for the new process. This file or process name is sent to the new
process in its startup message. If you do not include the IN option, the new
process uses the IN file of the current TACL (usually your home terminal). If
you include IN with no name, spaces are sent as the name of the input file.
TACL allows the IN file to be a DEFINE name, and passes the DEFINE name
to the process being executed. The process is responsible for handling the
DEFINE.
INLINE
specifies that the process is to be run under control of the INLINE facility (for
examples, see the TACL Programming Guide). This option also has the effect
of the NOWAIT option.
INSPECT { OFF | ON | SAVEABEND }
sets the debugging environment for the process being started. ON and
SAVEABEND select the Inspect symbolic debugger as the debugger; OFF
selects the DEBUG facility. SAVEABEND is the same as ON except that it
automatically creates a save file if the program abends (ends abnormally.) The
INSPECT option sets the debugging environment for the process you are
starting and for any descendants of that process. For more information, see the
DEBUG Command on page 8-48, SET INSPECT Command on page 8-193,
and SHOW Command on page 8-200 and the Inspect Manual.
INV variable-level [ DYNAMIC [ PROMPT variable-level ]]
is a variable level whose contents are extracted line by line and passed to the
process as the process reads from its IN file. If you include the word
DYNAMIC, the process waits for the variable to be refilled if it becomes empty
By including the PROMPT option, you can capture prompts in the specified
variable level: The most recent prompt string from the process is put into the
variable level. For additional information about the use of INV, see
Considerations on page 8-163.
JOBID num
specifies the new job ID for the new process.
LIB [ file-name ]
selects a user library file of object routines that are to be searched before the
system library file for satisfying external references in the program being run. If
you give the name of a library file, the program uses that library until you select
another library file. The library file name is linked to the program file and
remains in use for all runs of the program until you specify LIB without a file
name. If you do not give a file name, LIB deletes the previous selection.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-159
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
To run a program file with a user library, you must have write access to the
program file; the library file name is written into the object-file header of the
program at run time.
To run the program again with the same library, you can omit the LIB
parameter. To run the program again with no library (or with a different library),
include LIB (or LIB file-name).
MAXMAINSTACKSIZE number-of-bytes
where number-of-bytes specifies the maximum size, in bytes, of the
process main stack. The value provided is rounded up by operating-system
procedures to a page size boundary that is appropriate for the processor. The
specified size cannot exceed 32 megabytes (MB). The default value of 0D
indicates that the main stack can grow to 1MB. For most processes, the default
value is adequate.
Note. T h is o p tio n is a va ila b le w h e n th e d e fa ult co n figu ra tion settin g s o f the T A C L
p roce ss a re ch a ng e d . T o ch an g e the settin g s, se t th e T A C L co n fig u ra tio n p ara m ete r
C O N F IG R U N to P R O C E S S LA U N C H . F o r m o re in fo rm a tio n, se e th e
# S E T C O N F IG U R A T IO N o ptio n , C O N F IG R U N [ P R O C E S S C R E A T E |
P R O C E S S L A U N C H ] o n p a g e 9 -3 4 8 .
MAXNATIVEHEAPSIZE
number-of-bytes
MEM num-pages
is the maximum number of virtual data pages to be allocated for the new
process. Specify num-pages as an integer in the range 1 through 64. If you
omit this option, or if num-pages is less than the compilation-time value, the
compilation-time value is used instead.
NAME [ $process-name ]
is the name you are assigning to the new process. Specify $process-name
as an alphanumeric string of one to five characters (not including the dollar
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-160
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
sign); the first character must be alphabetic. (For network access, the name
must be no more than four characters.) If you omit this parameter, the new
process is not named and has only a CPU number and process number. If you
include NAME with no $process-name, TACL generates a name for the new
process. The name of the process appears in the destination control table
(DCT).
NOWAIT
means that TACL does not wait while the program runs but returns a command
input prompt after sending the startup message to the new process. If you omit
this option, TACL pauses while the program runs.
OUT [ list-file ]
is the output file of the new process. If you omit OUT list-file, the new
process uses the OUT file in effect for the current TACL (usually your home
terminal). If you include OUT with no list-file, spaces are sent as the
name of the output file. You cannot specify OUT if you specify OUTV or
WINDOW.
TACL allows the OUT file to be a DEFINE name, and passes the DEFINE
name to the process being executed. The process is responsible for handling
the DEFINE.
OUTV var-name
is a variable whose indicated level is cleared while retaining its type. Lines are
then added to it as the process writes to its OUT file. Prompt strings are not
written to the OUT variable. You cannot specify OUTV if you specify OUT or
WINDOW. For additional information about the use of OUTV, see
Considerations on page 8-163.
PFS num-pages
is the process file segment size, in 2048-byte pages, for the new process.
Specify num-pages as an integer value in the range 64 to 512. If you omit this
option, the number of pages is determined by a value in the program object
file.
PRI priority
specifies the execution priority of the new process; processes with higher
numbers run first. Specify priority as an integer in the range 1 to 199. If you
specify a priority greater than 199, the process runs at priority 199.
If the priority of the TACL process is 1 and priority for the new process is
not specified, TACL starts the new process at the priority of the TACL process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-161
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
If the priority of the TACL process is greater than 1 and priority for the new
process is not specified, TACL starts the new process at 1 less than the priority
of the TACL process.
If a $CMON process exists, it might specify a different priority for the new
process, depending on how it has been coded. See the Guardian
Programmers Guide for information about $CMON processes.
After a process has been started, the ALTPRI command can be used to alter
its priority.
STATUS variable
indicates why a process stops. Sets the variable to one of the values STOP,
ABEND, CPU, or NET when the process ends. To use STATUS, the TACL
process must be named.
SWAP swap-file
specifies the name of the file used to hold the virtual data of the process. When
a process is running, the system allocates a temporary file on the same volume
as the program file for swapping the data stack. When the process terminates,
the temporary swap file is automatically purged. If the swap file has a
permanent name, however, it is not purged.
With the SWAP parameter, you can:
Specify a permanent file name-the file contains an image of the data stack
when the process terminates.
Specify a different volume for the swap file (by specifying only a volume
name)-this is useful when the program file volume is full or busy. The
SWAP option also specifies the default volume for extended data
segments; see the Guardian Programmers Guide for more details.
SWAP can be used in debugging or for improving process performance.
For nonnative processes running with D42 or later software RVUs, the swapfile
is not used (or if provided, is ignored). The Kernel-Managed Swap Facility
(KMSF) manages swap space, including the file location, for the process. The
#PROCESSINFO built-in function always returns $volume.#0 for the SWAP
file-name. For more information about the KMSF facility, refer to the KernelManaged Swap Facility (KMSF) Manual.
TERM [\node-name.]$terminal-name
specifies the name of the home terminal (or a DEFINE that contains the name)
for the new process. If you omit this option, the new process uses the TACL
home terminal. For $terminal-name, specify a valid name for a terminal or
process: following the dollar sign, specify an alphanumeric string of one to six
characters; the first character must be alphabetic. For remote access, you can
have no more than five characters after the dollar sign.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-162
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
Considerations
These considerations apply to the RUN command:
The RUN command runs object files of type 100, 700, 800, or TACL programs.
You can specify DEBUG as the debugger with the SET INSPECT OFF command
or with the INSPECT OFF option of the RUN command. For more information, see
the SET INSPECT Command on page 8-193. For information about INSPECT, see
the Inspect Manual. For information about DEBUG, see the Debug Manual.
If you are not the super ID, you can debug only those programs whose process
accessor IDs match your user ID. For a description of process accessor IDs and
process creator IDs, see the Guardian Users Guide.
Privileged programs can be licensed (by the super ID) for use by users other than
the super ID. However, only the super ID can debug privileged programs. If you are
not the super ID and you try to use the RUND or RUNV command to debug a
licensed program, the program runs without entering a debug state.
For TNS/R systems, data swap files require 32,000 bytes more than the amount
specified in the MEM parameter. For example, if you specify MEM 64, TACL
doubles 64,000, rounds up to the next multiple of 4 (resulting in the same number
in this case), and adds 32,000 bytes, resulting in 160,000 bytes. Similarly, for a
MEM 3 setting TACL doubles 3,000 bytes, rounds up to the next multiple of 4
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-163
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
(8,000 bytes), and adds 32,000, resulting in 40,000 bytes. Ensure that your named
swap file has enough extent file space.
To use either the INV or the OUTV option, your TACL process (the one from which
you are starting the new process) must have a process name.
To use INV dynamically, you must include the NOWAIT option, so that control
returns to your TACL process. To send information, wait for the prompt variable.If
you plan to wait for more than one prompt, clear the prompt variable prior to the
next wait.
If you include either the IN or the INV option, you cannot use the INLINE option,
and the reverse. You cannot use the INLINE option if a process started previously
with the INLINE option still exists.
If you include the INLINE option, TACL waits until the newly started process
prompts for the first time; this guarantees that the initial output of the process is
available in the #INLINETO variable (if any) when TACL resumes operation.
When running a process that communicates with TACL (such as by setting IN or
OUT to the TACL process name, or by using TACL variables in INV or OUTV, or by
using the INLINE feature), be careful to coordinate TACL functions that enable the
communication (such as #IN or #OUT) with the matching mechanisms in that
process. Deadlock conditions can result if TACL tries to open a process for
communication at the same time that process is trying to open TACL for
communication.
When you include the LIB option, the operating system tries to resolve external
references to procedures in the program. It searches the library file specified with
the LIB option when the program was run. The date and time of the last
modification of LIB, as well as the disk address of the library file, are stored in the
program file. When you run a program without specifying a library with the LIB
option, the operating system compares the disk address and modification date of
the actual library file with the information about the library in the program file. If
they do not match, the message LIBRARY FILE CONFLICT is displayed. This
safe-guard prevents you from inadvertently running the wrong version of the library.
To use LIB, the user who runs a program should have write access to the program
file. For example, assume these two users:
GROUPA.USER1 GROUPB.USER2
and two files (with security CUCU) owned by USER1:
$DATA.USER1.PROG
$DATA.USER1.LIBFILE
These two attempts to run program PROG by USER1 succeed:
14> RUN PROG
15> RUN PROG / LIB LIBFILE /
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-164
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
USER2 (who does not have write access to PROG) can also run PROG, provided
the library LIBFILE has not been altered since its last use. If LIBFILE has changed,
however, and USER2 enters:
12> RUN PROG / LIB LIBFILE /
the attempt to run the program fails because USER2 does not have write access to
PROG so that external references can be resolved through the changed library file.
When you give a RUN command and the new process begins execution, TACL
pauses unless your RUN command includes the NOWAIT option. If the new
process does not take over break ownership, you can activate TACL while the
process runs by pressing the BREAK (or interrupt) key. TACL then runs
concurrently with the process. You can return TACL to its waiting state with the
PAUSE command.
If you specify the NOWAIT option in your RUN command, TACL returns to the
command input mode as soon as the new process reads its startup message.
Thus, NOWAIT means you do not have to wait for the new process to finish before
you can enter other commands. NOWAIT is especially useful when you start
several programs using the IN file-name option. The INLINE option also produces
the effect of the NOWAIT option.
You can use the STATUS option to avoid race conditions. For example, assume a
macro runs the same program more than once:
RUN laps /INV iv1 DYNAMIC,OUTV ov1,NOWAIT,NAME $z
STOP $z
RUN laps /INV iv2 DYNAMIC,OUTV ov2,NOWAIT,NAME $z/
The second time the program is run, if TACL receives the OPEN system
interprocess message for the second processs IN file before it receives the STOP
interprocess message for the first process, the process could receive a
nonexistent file error when it tries to open its IN file.
Before starting a second process with the same name as the first, the macro must
wait for the STOP command to finish. You can make the macro wait by providing a
STATUS variable in the first RUN command, then using the #WAIT built-in function
to ensure that TACL receives notification that the first process has stopped before
it starts the second one.
For example:
RUN laps /INV iv1 DYNAMIC,OUTV ov1,NOWAIT,NAME $z,STATUS
zs/
STOP $z
#WAIT zs
RUN laps /INV iv2 DYNAMIC,OUTV ov2,NOWAIT,NAME $z/
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
Similarly, these commands also run a TEDIT process on the \CHICAGO system,
because the current default node name is used for file-name expansion:
14> SYSTEM \CHICAGO
15> TEDIT
A program file, however, must reside on the system where it runs; the command:
14> RUN \DETROIT.MYPROG
attempts to run a program file named:
\DETROIT. default-volume. default-subvolume.MYPROG
If no such program file exists on the remote system, a message is displayed
indicating that the file does not exist. See the Expand Management Programming
Manual for further information on creating remote processes.
If you specify more than one out-run-option, TACL returns Option conflicts with
another option.
If the PFS option is out of range, TACL returns Expecting a number or an
arithmetic expression (Its value must be between 64 and 512 inclusive).
Redirection abilities of the OSH command utility can be used. For more information
on redirection, see Section 6, Open System Services Shell and Utilities Reference
Manual.
These conditions apply to the use of the RUN command for starting TACL processes:
TACL will not be able to detect the end of the INLINE process.
The output displayed might not be synchronized with the command entered
using the inline prefix.
Examples
1. This implicit RUN command runs the text editor program named TEDIT that
resides in the file $SYSTEM.SYSTEM.TEDIT:
14> TEDIT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-166
U T IL S :T A C L C om m an d s a nd F u nctio ns
R U N [D |V ] C o m m a n d
2. This command runs the program APP1 in the current default subvolume:
15> RUN APP1
3. This command also runs APP1:
16> RUN APP1 / IN APP1IN, OUT APP1OUT, CPU 2, &
16> &NAME $PROC1, NOWAIT /
It also specifies:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-167
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E G IN F O C o m m a n d
SEGINFO Command
Use the SEGINFO command to display a table of information about all the TACL
segment files in use by your TACL process.
SEGINFO
SEGINFO displays its information under this heading line:
Segment
File
Access
Pgs
Now
Pgs
Max
Bytes
Now
Bytes
Max
UC
Directory
Access
Pgs Now
Pgs Max
Bytes Now
Bytes Max
is the maximum number of bytes that the segment file can hold.
UC
is the use count for the segment file. Use count is a count of
variables in the segment that are being used by your TACL at
this instant. A variable is in use if it is being invoked, is being
used for process I/O, is in the use list, is in a pushed use list, is
the home directory, or is a pushed home directory. The use
count also includes one count for the segment file being
attached.
Directory
For more information about segment files, see Section 6, The TACL Environment.
Example
24> SEGINFO
Segment File
$EM2.#1242
$SYSTEM.SYSTEM.TACLSEG
F
$EM2.FURD.MYSEG
Access
PR
SH
Pgs
Now
8
56
Pgs
Max
1024
1024
Bytes
Now
10584
111340
Bytes
Max
2097152
2097152
%
0
5
UC
5
3
Directory
:
:UTILS.1
SH
76
1024
29676
2097152
:MYDIR.1
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-168
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E M S T A T P ro gram
SEMSTAT Program
Use the SEMSTAT program to print the Binary Sempahore (BINSEM) usage
information and statistics for a process whose ID or process name is provided.
Syntax to invoke the command:
SEMSTAT {-procname <name> | -pin <pin> [-brief | -full |
-wide |-clear_stats]}
<name> or
<pin>
Security Considerations
The SEMSTAT program is accessible to users with appropriate accessibility rights for a
process. The following list describes the accessibility rights for various users:
Users with the same process access ID as the process of interest. Both GROUP
and USER IDs must match.
Group Managers of the process of interest (that is GROUP,255).
Processes that are members of the SUPER group (that is SUPER.*).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-169
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E M S T A T P ro gram
Examples
The SEMSTAT program prints BINSEM statistics for each BINSEM used by the
specified process. The statistics are printed in a tabular format and are categorized as
the following heading rows:
Sem ID
Acquisitions
Tot. Cont.
Mult.Cont.
Cur. Cont.
Max. Cont.
Create Date
Create Time
Serial Number
Timeouts
Forced
Forsaken
Samples
1.Brief Format:
semstat /cpu 1/ -pin 843
SEMSTAT utility -- T9050J01 - (01AUG12) - (18JUN12) - (AWT)
(c) Copyright 2011 Hewlett Packard Development Company, L.P.
Acquisitions
Tot. Cont.
Mult. Cont.
Cur. Cont.
Max. Cont
--------------------------------------------------------------------------0
8225
8225
8225
7851
7833
30
8225
8225
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-170
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E M S T A T P ro gram
2.Full Format
semstat /cpu 1/ -pin 843 -full
SEMSTAT utility -- T9050J01 - (01AUG12) - (18JUN12) - (AWT)
(c) Copyright 2011 Hewlett Packard Development Company, L.P.
Tot. Cont.
Mult. Cont.
Cur. Cont.
Max. Cont
Timeouts
Forced
Forsaken
--------------------------------------------------------------------------0
8225
06-26-2012
01:30:14
32
8225
06-26-2012
01:30:14
33
8225
7851
7833
30
06-26-2012
01:30:14
34
8225
06-26-2012
01:30:14
35
8225
06-26-2012
01:30:14
36
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-171
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E M S T A T P ro gram
The following example first displays BINSEM Statistics for Process 1,945, and then
displays the cleared statistics after using -clear_stats option:
SYSTEM STARTUP 49> semstat -pin 945
SEMSTAT utility -- T9050J01 - (01AUG12) - (18JUN12) - (AWT)
(c) Copyright 2011 Hewlett Packard Development Company, L.P.
Acquisitions
Tot. Cont.
Mult. Cont.
Cur. Cont.
Max. Cont
--------------------------------------------------------------------------0
2593
2593
2593
2593
2593
2538
2535
31
Acquisitions
Tot. Cont.
Mult. Cont.
Cur. Cont.
Max. Cont
--------------------------------------------------------------------------0
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-172
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-173
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
REPORT report-name
SELPRI num
value
is a value to be associated with attribute-name. For value, specify a parameter
that is valid for the specific attribute. The values available for the various
attributes are described in these paragraphs.
LIKE define-name
specifies that the working attribute set is to have the same attributes and values as
the existing DEFINE named in the LIKE clause. You can modify those attributes or
add new attributes with attribute-spec entries that follow the LIKE clause.
Considerations
There is a special class of DEFINE names that begins with an equal sign plus an
underscore (=_). These names are reserved for TACL use only. Do not try to
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-174
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
create DEFINE names that begin with these two characters, except for specific
purposes that are described in application product documentation.
When an error occurs for the SET DEFINE command, no attributes or values are
changed in the working attribute set.
After you have set an attribute value, it persists until you reset it. You can reset an
attribute value explicitly with the RESET DEFINE command or with another SET
DEFINE command. You can reset a value implicitly by changing the CLASS
attribute.
If you log on from a logged-on TACL process, TACL preserves existing DEFINEs.
If you start a new TACL process from your existing TACL process, the new TACL
process does not inherit existing PARAM values.
When a backup TACL process takes over, TACL deletes existing DEFINEs.
The primary attribute-name value specification is the CLASS attribute, which is
specified as:
CLASS { CATALOG | DEFAULTS | MAP | SEARCH | SORT | SPOOL |
SUBSORT | TAPE }
The default is CLASS MAP. The CLASS attribute works as a DEFINE subtype, and
the seven classes have different uses:
CATALOG
makes a correlation between a logical catalog and an actual subvolume for
NonStop SQL/MP.
DEFAULTS
holds the standard default values of a process (such as the default volume).
MAP
makes a correlation between a logical device and an actual file.
SEARCH
specifies a search list of subvolumes for a program; the SEARCH class is
similar in functionality to the TACL #PMSEARCHLIST built-in variable.
SORT and SUBSORT
set parameters for FastSort processes and parallel SORTPROG processes.
SPOOL
sets parameters for the Spooler subsystem.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-175
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
TAPE
is used for accessing labeled tapes.
The CLASS attribute establishes a different initial working attribute set for each
class:
For CLASS CATALOG, the working attribute set always consists of the
SUBVOL attribute only (a required attribute that has no default value):
SUBVOL subvol-name
For subvol-name, give the name of an existing subvolume; the format is:
[[\node-name.]$volume.] subvol
The SUBVOL attribute specifies a subvolume to be used as a catalog by
NonStop SQL/MP. When you use the DEFINE name in a command, NonStop
SQL/MP substitutes the catalog subvolume name for the DEFINE name.
For CLASS DEFAULTS, the working attribute set consists of the CATALOG,
VOLUME, SWAP, LANG, and LC attributes.
The description of these attributes:
VOLUME
specifies the default node, volume, and subvolume names.
SWAP
specifies the node and volume names to be used for a swap file.
CATALOG
specifies the node, volume, and subvolume names of an SQL catalog.
LANG
determines values for all Internationalization (I18N) environment variables
in the absence of other LC variables.
LC_ALL
determines values of all I18N environment variables and has precedence
over all other LC variables and LANG variables.
LC_COLLATE
determines how characters are ordered, sorted, grouped, and translated.
LC_CTYPE
determines character handling.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-176
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
LC_MESSAGES
determines how messages and process interactive responses are
formatted.
LC_MONETARY
determines how currency representations are formatted.
LC_NUMERIC
determines how numbers are represented.
LC_TIME
determines how dates and times are formatted.
Each of these attributes is case-sensitive and can be up to 256 characters.
They can be set to any value, although to be effective, the value must match
one of the values supported in the process it is used. Supported values are
described in the Internationalization library.
For CLASS MAP, the working attribute set always consists of only the FILE
attribute (a required attribute that has no default value):
FILE file-name
For file-name, specify a file name; the format is:
[[[\node-name.]$volume.] subvol.] file-name
The FILE attribute specifies the file name to be used in place of MAP DEFINE
name. When you use the DEFINE name in a command or procedure call, the
file system substitutes the value associated with the FILE name for the
DEFINE name. (See the examples for the ADD DEFINE Command on
page 8-9.)
You can use a CLASS MAP DEFINE in TACL wherever a file name is
accepted. On a RUN or #NEWPROCESS command, however, the new
process must be able to handle a DEFINE name in place of a file name if you
include a CLASS MAP DEFINE.
For CLASS SORT, the working attribute set consists of the attributes listed in
Table 8-4 on page 8-179. All attributes are optional.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-177
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
For CLASS SPOOL, the working attribute set consists of the attributes listed in
Table 8-5 on page 8-182. The only required attribute is the LOC attribute.
For CLASS SUBSORT, the working attribute set consists of the attributes listed
in Table 8-6 on page 8-184. The only required attribute is the SCRATCH
attribute.
For CLASS TAPE, the working attribute set consists of all the attributes listed
in Table 8-8 on page 8-186, as well as any values set or defaulted for those
attributes. The only required attribute for a TAPE DEFINE is VOLUME, and
then only when you specify USE IN. Table 8-8 describes the CLASS TAPE
attributes; those marked with an asterisk (*) correspond to fields in the tape
system labels.
Because the CLASS attribute works as a DEFINE subtype, you should remember
these points when you use SET DEFINE:
Attributes are set in the order in which they are specified in the SET DEFINE
command.
Setting the CLASS attribute establishes a new working attribute set that
consists of all the attributes associated with that class, each with its initial
setting.
You cannot set an attribute that is not associated with the current CLASS. For
example, if the current CLASS is DEFAULTS, you cannot enter SET DEFINE
LABELS IBM.
To avoid errors or unexpected results with the SET DEFINE command, set the
CLASS attribute first. You can do this in a separate SET DEFINE command,
with a LIKE clause in a SET DEFINE command, or as the first attribute in a
SET DEFINE command. However, be careful not to specify a LIKE clause in
the same SET DEFINE command with a CLASS clause.
If you enter a SET DEFINE command with a LIKE clause, a later ADD DEFINE
command will create a DEFINE identical to the one named in LIKE define-name as
long as you do not modify any attributes. These points apply:
If the CLASS of LIKE define-name is the same as the current CLASS, all the
attributes in the working attribute set are set to the values of define-name. For
example, if an attribute has no value in LIKE define-name, that attribute has no
value in the working attribute set.
If the CLASS of LIKE define-name is different from the current CLASS, a new
working attribute set is established, corresponding to the CLASS of definename, and with attribute values set as in define-name.
Any attribute specifications that follow a LIKE clause in a SET DEFINE command
modify the attribute values established by the LIKE clause.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-178
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
The same set of DEFINE attributes can be configured for a generic process
through SCF. For the syntax, see the SCF Reference Manual for the Kernel
Subsystem.
Function
BLOCK size
CPU cpu-num
CPUS
{ ( cpu-num [ , cpu-num ] ... ) | ALL }
MODE
{ AUTOMATIC | MINSPACE | MINTIME }
AUTOMATIC
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-179
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
MINSPACE
MINTIME
NOTCPUS
( cpu-num [ , cpu-num ] ... )
PRI priority
PROGRAM file-name
SCRATCH file-name
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-180
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
SEGMENT size
SUBSORTS
( DEFINE-name [ , DEFINE-name ] ... )
SWAP file-name
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-181
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
BATCHNAME batch-name
COPIES num
The default is 1.
Specifies a form name for jobs created by the
DEFINE, denoting requirements (such as special
paper) associated with a job
FORM form-name
HOLDAFTER { ON | OFF }
LOC
[\node-name.] $collector
[.group-name[.dest ] ]
MAXPRINTLINES num
MAXPRINTPAGES num
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-182
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
OWNER
{ group-name.user-name } |
{ group-num.user-num }
PAGESIZE num
SELPRI num
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-183
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
BLOCK size
CPU cpu-num
PRI priority
SCRATCH file-name
Specifies the name of a disk file for use as a sort work file
If the file already exists, it must be unstructured. A volume
name alone is acceptable. This attribute is required.
SEGMENT size
SWAP file-name
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-184
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Description
001
002
If you specify USE IN or EXTEND, you must include VOLUME and specify
LABELS ANSI or LABELS IBM. If you specify REELS, the value must equal
the number of volumes specified in VOLUME.
003
If you specify VOLUME, you must also specify LABELS ANSI, LABELS IBM,
or LABELS IBMBACKUP. If you specify LABELS, you must also specify
VOLUME.
004
If you specify LABELS ANSI, you must not specify the EBCDIC attribute, and
the reverse.
005
006
If you specify DEVICE, you cannot specify SYSTEM in the same DEFINE,
and the reverse.
007
008
If you specify VOLUME SCRATCH, you must not specify USE IN or USE
EXTEND.
009
010
011
If you specify LABELS IBMBACKUP, the system you specify in the SYSTEM
or DEVICE attribute must have an operating system RVU of C20 or later.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-185
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
* BLOCKLEN block-length
DEVICE $device-name
Specifies the name of the tape device where the tape file
is to be mounted
If you specify a tape drive on a remote system, the
system must be a node on your network. If you omit
both DEVICE and SYSTEM attributes, tapes must be
mounted on the local system. If you specify DEVICE,
you must omit SYSTEM.
* EXPIRATION date
Specifies the expiry date for this tape file (the first date
on which the file can be overwritten)
Specify month, day, and year, such as DEC311990. If
you specify EXPIRATION, you must omit RETENTION.
* FILEID file-name
* FILEID file-name
* FILESECT volume-order
* FILESEQ file-order
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-186
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
* GEN gen-number
LABELS
{
ANSI |
IBM |
OMITTED |
BYPASS |
BACKUP |
IBMBACKUP
}
* OWNER owner-id
MOUNTMSG "text"
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-187
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
* RECFORM { F | U }
* RECLEN record-length
REELS volumes
SYSTEM \node-name
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-188
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
Function
TAPEMODE
{ STARTSTOP | STREAM }
* VERSION number
VOLUME
{ vol-id | SCRATCH }
* Attributes marked with an asterisk have corresponding fields in the tape system labels. See the description of
tape label formats in the Guardian Users Guide.
Examples
1. This command establishes a working attribute set that describes a tape file residing
on three ANSI standard tape volumes (1, 2, and 3). This file is to be read (USE IN),
and the system is to do standard label processing:
13> SET DEFINE CLASS TAPE, LABELS ANSI, VOLUME (1,2,3),&
13> &REELS 3, USE IN
2. In this example, a SET DEFINE command establishes a working attribute that
contains the attributes common to two DEFINEs that are to be created. Each is a
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-189
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T D E F IN E C o m m a n d
CLASS TAPE DEFINE that describes a tape file residing on volume 30 of an ANSI
standard labeled tape mounted on tape drive $TAPE2.
Next, a SHOW DEFINE command displays the status of the current working
attribute set. Finally, two ADD DEFINE commands create the DEFINEs and set the
attributes that are unique to each DEFINE, which in this case are the file names
MAYRCDS and JUNRCDS:
14> SET DEFINE CLASS TAPE, LABELS ANSI, FILEID empty,&
14> &DEVICE $tape2, VOLUME 30
15> SHOW DEFINE
CLASS
VOLUME
LABELS
FILEID
DEVICE
TAPE
30
ANSI
empty
$TAPE2
=one
TAPE
30
ANSI
mayrcds
$TAPE2
DEFINE NAME
CLASS
VOLUME
LABELS
FILEID
DEVICE
=two
TAPE
30
ANSI
junrcds
$TAPE2
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-190
U T IL S :T A C L C om m an d s a nd F u nctio ns
Consideration
DEFMODE is always set ON when TACL is first started, and whenever you log on from
the logged-off state.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-191
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T H IG H P IN C o m m a n d
Considerations
This command sets the built-in variable #HIGHPIN. Like other built-in variables,
#HIGHPIN can be set, expanded, pushed, and popped.
Use SHOW HIGHPIN to display the current value of #HIGHPIN interactively, or
type #HIGHPIN to expand the variable in a routine.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-192
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T IN S P E C T C o m m a n d
Considerations
Your selection of the Inspect debugger as the default debugger is effective until
you enter another SET INSPECT command or until you log off. After you log off,
the Debug program once again becomes the default debugger. However, if you
enter a SET INSPECT command and log on again without logging off, Inspect
remains the default debugger.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-193
U T IL S :T A C L C om m an d s a nd F u nctio ns
SETPROMPT Command
Use the SETPROMPT command to change the TACL prompt. By default, TACL
prompts with a history number and a greater-than sign (>) followed by a space.
SETPROMPT { SUBVOL | VOLUME | BOTH | NONE }
SUBVOL
displays the current subvolume, followed by the command number, a greater-than
sign, and a space.
VOLUME
displays the current volume, followed by the command number, a greater-than
sign, and a space.
BOTH
displays the current volume and subvolume, followed by the command number, a
greater-than sign, and a space.
NONE
displays the command number, a greater-than sign, and a space. NONE is the
default.
Examples
1. This example illustrates how to set your prompt to your current subvolume:
12> SETPROMPT SUBVOL
BOOK 13>
2. You can also set your prompt to both your volume and subvolume by entering:
BOOK 13> SETPROMPT BOTH
$STEIN BOOK 14>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-194
U T IL S :T A C L C om m an d s a nd F u nctio ns
Considerations
To clear any swap volume previously set, use the SET SWAP command without
the $volume-name parameter.
Any RUN command that explicitly specifies a swap volume overrides the previous
SET SWAP $volume-name command.
If no SET SWAP command has been issued, and no swap volume is specified in a
RUN command, the swap volume defaults to the volume in which the program is
stored.
This command alters the SWAP attribute of the =_DEFAULTS DEFINE.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-195
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T T IM E C o m m a n d (S u pe r-G ro up O nly)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-196
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T T IM E C o m m a n d (S u pe r-G ro up O nly)
Considerations
Example
1. To set the system clock to 8:01 p.m. on July 9, 2004, enter:
34> SETTIME JUL 9 2004, 20:01
2. You can see the new time by entering the TIME command:
35> TIME
July 09, 2004 20:01:ss
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-197
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T V A R IA B LE C o m m a n d
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-198
U T IL S :T A C L C om m an d s a nd F u nctio ns
S E T V A R IA B LE C o m m a n d
MACRO
specifies that text is a TACL macro.
ROUTINE
specifies that text is a TACL routine.
TEXT
specifies that text is simply text (it has no special meaning to TACL).
variable-level
is the name of an existing variable level, of the form:
variable-name[. level-num]
If you omit . level-num, the top level of the variable is assumed.
text
is the new contents of the variable level. If the IN option is supplied, you cannot
specify text.
built-in-variable
is the name of a built-in variable.
built-in-text
is the new value for the built-in variable.
Considerations
The syntax and operation of the SET VARIABLE command is the same as that of
the #SET built-in function.
The SET VARIABLE command replaces the current contents of variable-level with
the specified text or, if you use the IN option, the contents of the specified file.
Unless you specify a TYPE option, the variable type remains the same.
You cannot use a text string with the IN option, nor can you use the IN option with
a built-in variable.
The SET VARIABLE command cannot put leading or trailing spaces into a variable
level.
Example
This example illustrates the use of the SET VARIABLE command. This command sets
a variable level named VARA, of type MACRO, to the text *,USER SUPPORT.ALICE:
25> SET VARIABLE / TYPE MACRO / vara *,USER SUPPORT.ALICE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-199
U T IL S :T A C L C om m an d s a nd F u nctio ns
SH O W Com m and
SHOW Command
Use the SHOW command to display the values of attributes set with the SET
command.
SHOW [ / OUT list-file / ] [ attribute [ , attribute ] ... ]
OUT list-file
specifies a device, or a sequential file accessible to the sequential I/O (SIO) facility,
that is to receive a listing of command output. If you omit this option, TACL writes
the listing to its current OUT file.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
attribute
is any attribute controlled by the SET command. Currently, these attributes are
controlled by SET:
DEFMODE
is the enable mode (ON or OFF) for DEFINEs. For more information, see the
RUN[D|V] Command on page 8-156 and SET DEFINE Command on
page 8-173.
INSPECT
is the name of the alternate symbolic debugging utility. See also the DEBUG
Command on page 8-48, the SET INSPECT Command on page 8-193, the
RUN[D|V] Command on page 8-156, and the Inspect Manual.
HIGHPIN
is used to establish the default PIN range for processes started by the current
TACL when there is no HIGHPIN directive on a RUN command or
#NEWPROCESS call.
SWAP
is the volume that holds virtual data during memory swaps of the user data
stack.
Consideration
Entering SHOW without specifying any attributes causes all SET attributes to be
displayed.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-200
U T IL S :T A C L C om m an d s a nd F u nctio ns
SH O W Com m and
Examples
1. This command displays the status of the INSPECT and SWAP attributes:
13> SHOW SWAP,INSPECT
Swap $RALPH
Inspect ON
2. To see all attributes currently set, enter:
14> SHOW
Defmode ON
Highpin ON
Inspect ON
Swap
The display shows that DEBUG is the debugging utility in effect, DEFMODE is set ON,
and that no swap volume has been set.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-201
U T IL S :T A C L C om m an d s a nd F u nctio ns
S H O W D E F IN E C o m m a n d
Considerations
Entering SHOW DEFINE with no parameter produces a display of the names and
current values of all attributes that are currently set or that have default values.
Required attributes that have no current value are listed with ?? as the value.
Optional attributes that have no current value are not listed. Attributes whose
values violate the consistency rules (see Table 8-7 on page 8-185) are flagged with
an asterisk (*).
The SHOW DEFINE command checks for consistency among the attributes in the
working attribute set. If the attributes are inconsistent (that is, if at least one has a
value that conflicts with that of another attribute), the inconsistent attribute is
flagged with an asterisk, and a warning message is displayed; for example:
81> SHOW DEFINE
CLASS TAPE
* VOLUME 1265
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-202
U T IL S :T A C L C om m an d s a nd F u nctio ns
S H O W D E F IN E C o m m a n d
* LABELS OMITTED
Current attribute set is inconsistent, check number 3
If the attributes are incomplete (that is, if a required attribute is missing), a warning
message is displayed, and the value for the missing attribute is displayed as ??. For
example:
87> SHOW DEFINE
CLASS MAP
FILE ??
Current attribute set is incomplete
TACL returns an error if you specify an attribute that is not a member of the working
attribute set (an attribute that is not associated with the current CLASS).
To obtain additional error information, use #ERRORNUMBERS.
Examples
1. To display the value currently set for the DEVICE attribute, enter:
92> SHOW DEFINE DEVICE
DEVICE $TAPE
2. This SHOW DEFINE command displays a working attribute set that specifies a
CLASS TAPE DEFINE:
95> SHOW DEFINE
CLASS TAPE
VOLUME ( 25436, 75444, 23121 )
LABELS IBM
USE IN
3. This command displays all working attributes and the value for each:
98> SHOW DEFINE *
CLASS TAPE
VOLUME ( 25436, 75444, 23121 )
LABELS IBM
REELS
OWNER
FILESECT
FILESEQ
FILEID
RETENTION
EXPIRATION
GEN
VERSION
RECFORM
BLOCKLEN
RECLEN
DENSITY
RECLEN
USE IN
DEVICE
EBCDIC
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-203
U T IL S :T A C L C om m an d s a nd F u nctio ns
MOUNTMSG
SYSTEM
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-204
S H O W D E F IN E C o m m a n d
U T IL S :T A C L C om m an d s a nd F u nctio ns
S IN K C o m m a n d
SINK Command
Use the SINK command to invoke a function but discard its result. SINK can discard
nonnumeric results as well as numeric ones.
SINK [ text ]
Consideration
Use of the SINK command discards error indications returned by a function. Therefore,
the use of SINK is not recommended unless you do not need to know if an error
occurred. For example, if you want to purge a file but do not care if you try to purge the
file and the file does not exist, use SINK to discard any error that might occur.
Example
This command loads the TACL library file MYMACS into memory, but does not display
the list of variables that were modified:
14> SINK [#LOAD mymacs]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-205
U T IL S :T A C L C om m an d s a nd F u nctio ns
STATUS Command
Use the STATUS command to display information about one or more running
processes. The STATUS command is an alias for the #XSTATUS built-in function.
STATUS [ / OUT list-file / ] [ range ] [ , condition ] ...
[ , DETAIL ] [ , STOP ] [ , FORCED ]
OUT list-file
specifies a device, or a sequential file accessible to the sequential I/O (SIO) facility,
that is to receive the STATUS output. If you omit the OUT option, the STATUS
listing goes to the OUT file in effect for the current TACL (usually the home
terminal).
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
status information to the end of the file.
range
is any of these:
[\node-name.] cpu,pin
[\node-name.] cpu-number
[\node-name.]$process-name
[\node-name.]*
\node-name
requests the status of all specified processes running in \ node-name.
cpu,pin
requests the status of a particular process.
cpu-number
requests the status of all processes running in a particular CPU.
$process-name
requests the status of a particular named process or process pair.
*
requests the status of processes running in all CPUs.
If you omit range, STATUS reports on the last process started by the current TACL,
or for which TACL last paused, if that process is still running. is any one of these:
GMOMJOBID $process-name. num
PRI [ priority ]
PROG [ program-file-name | file-name-template ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-206
U T IL S :T A C L C om m an d s a nd F u nctio ns
TERM [ $terminal-name ]
USER [ user-id ]
GMOMJOBID $process-name.num
specifies processes with the given job ancestor ID. num is a signed integer.
LOADED [loaded-file-name | file-name-template]
is used to get the information about processes that are using given loaded
files. The same functionality can be used with built-in #XSTATUS.
LOADED specifies processes using the given loaded file name. If you omit the
loaded file specification, LOADED defaults to the program file name of the
current TACL.
You can use file-name-template characters in any field of the file specification
except the system field. The template characters are:
* Matches zero or more characters
? Matches a single character
Template characters cannot match a volume identifier($) of a field separator(.).
PRI [ priority ]
specifies processes whose execution priority is less than or equal to the priority
given. If you omit priority, STATUS reports on processes whose priorities are
less than that of the current TACL.
PROG [ program-file-name | file-name-template ]
specifies processes with the given program file name. If you omit the program
file specification, PROG defaults to the program file name of the current TACL.
You can use file-name-template characters in any field of the file specification
except the system field. The template characters are:
*
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-207
U T IL S :T A C L C om m an d s a nd F u nctio ns
USER [ ident ]
specifies processes created by a particular user, where ident is either groupname.user-name or group-id, user-id. If you include USER without ident,
STATUS reports on processes whose creator accessor ID matches your user
ID.
If you specify more than one condition, STATUS reports on all processes that
satisfy all the conditions.
DETAIL
gives a detailed display of process status.
STOP
specifies that TACL is to try to stop each process for which information is
displayed (except the TACL process issuing the command), subject to the
normal rules governing which processes you are allowed to stop. TACL
displays a confirmation message asking if you want to stop the processes
specified by the command line. TACL does not indicate whether the STOP
option succeeds or fails.
FORCED
forces TACL to stop the processes specified by the command line. In this case,
TACL will not prompt you with a confirmation message.
Considerations
STATUS, entered with no range or condition parameters, reports the status of the
last process TACL created, or for which TACL last paused, regardless of the CPU.
If that process is no longer running, STATUS reports nothing.
The STATUS command displays information for I/O processes when appropriate
(for example, user 255,255 and the $OSP terminal). To eliminate the display of I/O
processes, add PRI 199 to the command. For example:
STATUS *, USER, PRI 199
A STATUS cpu,pin request displays both processes if the requested process is part
of a process pair. If you request information about a system-image process, TACL
displays the status of the single system-image process.
If you specify a single process and the process does not exist, TACL returns
Process does not exist.
If the node name for a process cannot be retrieved by the STATUS program, the
node name for the home terminal will be displayed.
If you specify a range of processes and none of the processes exist, TACL
displays nothing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-208
U T IL S :T A C L C om m an d s a nd F u nctio ns
File-name-template is not supported for the options PROG and LOADED used
together. For example:
STATUS *, PROG file-name-template, LOADED file-name-template
will return no information.
If file-name-template is specified with the LOADED option, STATUS will display all
the processes associated with that loaded file.
If the program file name for a process cannot be retrieved by the STATUS
program, path to info down is displayed in the output instead of the file
name.
For the attenuated display:
> STATUS *,TERM
Process
Program file
Hometerm
$Y906
1,158 150
$MPMA
3,90
129
$Z2
$MP
5,80
150
$Z3
($MP)
15:27
Primäre
READY
Priority: 150
Wait State: %000
Userid: 104,111
(SDEV.FRED)
Myterm: \PRUNE.$Z3
Program File Name: <Path to info down>
Swap File Name: $MG.#0012980
Current Extended Swap File Name: $MG.TEST.TACLSEGF
Process Time: 0:0:1.974
Process Creation Time: March 29, 2004 15:22:24.101230
Process States: LOGGED ON, FORCED LOW, RUNNABLE
GMOMJOBID:
If the processor for the disk process controlling the disk where the program file
resides fails, the process file name is unavailable.
If the output of the STATUS command includes the Swap File Name parameter
and no swap file name has been set with either (or both) the SWAP swap-file
option of the RUN command or the SET SWAP [ $volume-name ] command, a
dummy file name, "$vol.#0", is returned. In this case, #vol is the name of the
physical volume that the operating system has selected for storing the swap file. In
the following example, $SYSTEM.#0 is a dummy file name. The operating
system is using the $SYSTEM volume if a swap file is required.
Swap File Name: $SYSTEM.#0
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-209
U T IL S :T A C L C om m an d s a nd F u nctio ns
The output from the STATUS command can include information for OSS
processes: the OSS program pathname, OSS arguments, and OSS process ID.
Currently, only local OSS information can be obtained. For pre-D30 software
RVUs, OSS information cannot be obtained.
In the summary form of the STATUS command, the short form of the OSS program
pathname is output. In the detailed form of the STATUS command, the fully
qualified OSS program pathname, the OSS arguments, and the OSS process ID
are output.
The Program file display is limited to 26 characters. An OSS pathname can have
a maximum of 1024 characters. If the fully qualified OSS program pathname is 26
or fewer characters, then the entire name is output, as illustrated in this example:
STATUS *,USER
Process
Pri PFR %WT Userid Program file
$DCED X 0,339 155
004 255,161 /opt/dcelocal/bin/dced
Hometerm
$ZTNT.#P
If the file name portion of the name is not available, "No OSS file name" is
output for the file name. If no path name is available, a generic ZYQ-file program
file name is output.
The OSS program pathname should not be used as input into a TACL command
because it is not formatted in a way that a TACL process can process.
In the detailed STATUS display, the OSS pathname, the first 1024 bytes of the
arguments of the command that created the OSS process, and the OSS process
ID (a unique identifier for an OSS process) are output:
STATUS 0,339,DETAIL
System: \FOXII
November 13, 1995 10:53
Pid: 0,339
($ZDCED)
Primary
Priority: 155
Wait State: %004
(LDONE)
Userid: 255,161
(SUPER.DCE)
Myterm: $ZTNT.#PTY000X
Program File Name: $OSS001.ZYQ00002.Z0000VK0
Swap File Name: $DCE.#0000249
Current Extended Swap File Name: $DCE.#0000250
Library File Name: $SYSTEM.ZSRL.LDCE
Process Time: 0:0:15.859
Process Creation Time: November 13, 1995 10:13:06.028548
Process States: RUNNABLE
GMOMJOBID:
OSS Pathname: /opt/dcelocal/bin/dced
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-210
U T IL S :T A C L C om m an d s a nd F u nctio ns
OSS Arguments: -b
OSS PID: 882049029
The output of the TACL STATUS command along with the DETAIL option now
display ProgramDataModel, IPUAssociation, and IPUNumber depending on the
following criteria:
Examples
1. To view the status of user 103, 141 enter:
14> STATUS *, user 103, 141
Process
$Y09M
9
9
$Y09M
9
0,193
Pri
168
0,611
168
1,121
168
PFR
%WT
001
Userid
103,141
Program file
$SYSTEM.SYS10.TACL
Hometerm
000
103,141
/bin.sh
$ZTNT.#PTA8AE
000
103,141
$SYSTEM.SYS10.TACL
$ZTNT.#PTA8AE
$ZTNT.#PTA8AE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-211
U T IL S :T A C L C om m an d s a nd F u nctio ns
The bits in the wait field are numbered from left to right; thus, a wait state of
%003 means that bits 14 and 15 are set.
The group-id, user-id of the process accessor.
The name of the program file. For system processes, prog-name is
$SYSTEM.SYSnn.OSIMAGE. (Subvolume $SYSTEM.SYSnn contains the
operating system image currently in use; nn is a two-digit octal integer that
identifies that subvolume.)
The home terminal of the process.
The name of the user library file, swap file, and extended swap file, if you
requested the status of a single process (or a process pair) that is running with
a user library (such as one specified with the LIB option of the RUN command)
or swap files.
2. Including the DETAIL parameter in a STATUS command yields a display such as:
13> STATUS $TA8, DETAIL
System: \NEWYORK November 4, 2002 8:29
Pid: 1,31 ($TA8) Primary
Priority: 150
Wait State: %001 (LREQ)
Userid: 101,93 (SD.JKR)
Myterm: $TPQA8
Program File Name: $SYSTEM.SYS01.TACL
Swap File Name: $SYSTEM.#0000094
Current Extended Swap File Name: $TEMP.#0001203
Process Time: 0:1:47.870
Process Creation Time: October 22, 2002 22:12:19.599414
Process States: NO MESSAGES, LOGGED ON, RUNNABLE
GMOMJOBID:
System: \NEWYORK November 4, 2002 8:29
Pid: 2,35 ($TA8) Backup
Priority: 150
Wait State: %001 (LREQ)
Userid: 101,93 (SD.JKR)
Myterm: $TPQA8
Program File Name: $SYSTEM.SYS01.TACL
Swap File Name: $SYSTEM.#0000094
Current Extended Swap File Name: $TEMP.#0001203
Process Time: 0:0:2.238
Process Creation Time: October 22, 2002 22:12:21.426762
Process States: NO MESSAGES, LOGGED ON, RUNNABLE
GMOMJOBID:
The DETAIL option includes this information for the primary process and the
backup process (if it exists):
U T IL S :T A C L C om m an d s a nd F u nctio ns
%001
%002
%004
%005
User ID and name, Creator access ID (CAID) and its name, and Login name
(ALIAS).
Note. U se r ID is e q u iva len t to th e P ro ce ss a cce ss ID (P A ID ). C A ID is d isp la yed o n ly if
it d iffe rs fro m P A ID . T h e L o gin na m e is d isp la ye d o n ly if the cre a to r o f th e pro ce ss h a s
lo g g e d in u sin g th e A L IA S n am e .
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-213
U T IL S :T A C L C om m an d s a nd F u nctio ns
3. To stop all of your processes on the terminal where your TACL is running (except
the TACL process itself):
STATUS *, TERM, STOP
The following confirmation message is displayed:
This command will display the processes satisfying the
command parameters and then stop them. Do you really want to
stop the processes (y/[n])?
A process, started by an alias (sspaul) from a progid-ed (super.super) object
owned by support.prs, will have the following as the output to the STATUS
command with the DETAIL option.
Pid: 2,110
($PIPO)
Primary
Priority: 148
Wait State: %004
(LDONE)
Process access id: 20,33
(SUPPORT.PRS)
Creator access id: 255,255
(SUPER.SUPER)
Login name: sspaul
Myterm: $ZN018.#PT05WPE
Program File Name: $SYSTEM.PJ00WTAL.VPROC
Swap File Name: $SYSTEM.#0
Current Extended Swap File Name: $SYSTEM.#0
Process Time: 0:0:0.004
Process Creation Time: April 2, 2009 20:02:36.642570
Process States: RUNNABLE
GMOMJOBID:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-214
U T IL S :T A C L C om m an d s a nd F u nctio ns
STOP Command
Use the STOP command to request termination of a running process.
STOP [ [\node-name.]{$process-name | cpu,pin} ]
\node-name
is the system where the process resides.
$process-name
is the name of the process or process pair.
cpu,pin
is the CPU number and process number for the process.
Considerations
If a process terminates successfully, TACL does not display a message. Otherwise, the
STOP command displays information about the outcome of the termination request.
The possible outcomes are listed in Table 8-9.
Table 8-9. STOP Command Messages
Message
Meaning
Non-existent process-name
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-215
U T IL S :T A C L C om m an d s a nd F u nctio ns
STOP cannot stop the current TACL or its backup. Use the built-in function #STOP
instead.
Examples
1. To stop the last process you started from the current TACL, enter:
14> STOP
15>
2. If you started the process whose cpu,pin is 0,18, or if you are the super ID, you
can stop the process by entering:
14> STOP 0,18
15>
3. If you are a group manager and a member of your group started the process
named $END, or if you are the super ID, you can stop the process $END by
entering the process name or cpu,pin:
14> STOP $END 15>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-216
U T IL S :T A C L C om m an d s a nd F u nctio ns
SUSPEND Command
Use the SUSPEND command to temporarily suspend a process (or process pair) to
prevent it from competing for system resources.
SUSPEND [ [\node-name.]{$process-name | cpu,pin } ]
\node-name
is the system where the process resides.
$process-name
is the name of the process or process pair.
cpu,pin
is the CPU number and process number for the process.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-217
U T IL S :T A C L C om m an d s a nd F u nctio ns
Examples
1. To suspend the last process you started from the current TACL, enter:
14> SUSPEND
15>
2. If you started a process with cpu,pin 0,18, or if you are the super ID, you can
suspend the process by entering:
14> SUSPEND 0,18
15>
3. If you are a group manager and a member of your group started the process
whose name is $CLOCK, or if you are the super ID, you can suspend the process
by entering the process name or cpu,pin:
15> SUSPEND $CLOCK
16>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-218
U T IL S :T A C L C om m an d s a nd F u nctio ns
S W IT C H C o m m a n d
SWITCH Command
Use the SWITCH command to make your TACL backup the primary process,
initializing itself as though you had just logged on to it. The former primary process
becomes the backup. The SWITCH command is an alias for the #SWITCH built-in
function.
SWITCH
Considerations
To use the switch command, your TACL must have a backup process. To create a
backup process, include it in the TACL RUN command or use the BACKUPCPU
command.
The SWITCH command must be entered interactively. Do not include the SWITCH
command in an IN file specified in a command to run TACL; if you do so, TACL
performs the switch before processing other commands-and each switch causes
an initialization so that the TACL process continues to switch processors.
SWITCH establishes an initial logon state, resetting all ASSIGNs, PARAMs, and
DEFINEs, invoking the TACLLOCL file and your TACLCSTM file, and setting the
history buffer index to 1.
If an error occurs while TACL is trying to create the backup process or if the
backup CPU is down, TACL waits 3 minutes before trying to create the backup.
All events, such as a backup-create error or an I/O error event, and the error
details are logged to the primary or $0 collector. This format is used:
Example
Assume that the primary TACL process that controls your terminal is running in CPU 5,
and the backup TACL process is running in CPU 4. (To display the CPU numbers of
the processors where your TACL processes are running, use the WHO or STATUS
command.)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-219
U T IL S :T A C L C om m an d s a nd F u nctio ns
S W IT C H C o m m a n d
You can switch the functions of these processes (make the TACL process running in
CPU 4 the primary process and the process running in CPU 5 the backup) by entering
the SWITCH command:
24> SWITCH
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-220
U T IL S :T A C L C om m an d s a nd F u nctio ns
SYSTEM Command
Use the SYSTEM command to set the default system until you change it again or log
off. This command applies only to systems that are available in a network.
SYSTEM [ \node-name ]
\node-name
is the name of a new default system. If you omit \ node-name, the system on which
your TACL is running becomes the current default.
Considerations
The system you specify in a SYSTEM command is temporarily in effect. After you
enter a LOGON command, or a SYSTEM or VOLUME command with no following
parameters, your default system is again your logon default. (To change your logon
defaults, use the DEFAULT program.)
If you are running a remote TACL process, entering SYSTEM with no following
parameters establishes that remote system as your default system, instead of the
local system to which your terminal is connected.
These commands are not equivalent:
14> SYSTEM \ local-node-name
14> SYSTEM
The first invocation causes the network restrictions on file-name lengths to take
effect; the second does not. See the Expand Network Management and
Troubleshooting Guide for information on network file-name restrictions.
To view the default system, use the WHO command or the #DEFAULTS built-in
variable. If the WHO command does not display a current system, your current
system is the local system.
Examples
1. To specify \LONDON as the current default system, enter:
14> SYSTEM \LONDON
When you enter the WHO command, the display includes the current default
system (omitted when it is the same as the saved default):
15> WHO
...
Current volume: $BOOKS.TACL Current system: \LONDON
2. To return to your saved default system (established by the DEFAULT command):
16> SYSTEM
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-221
U T IL S :T A C L C om m an d s a nd F u nctio ns
S Y S T IM E S C o m m a n d
SYSTIMES Command
Use the SYSTIMES command to display the current date and time (in local civil time
and Greenwich mean time), the date and time when the system was last cold loaded,
and the date and time SYSGEN was last run.
SYSTIMES
Considerations
The SYSTIMES command displays four lines of information giving you the date
and time as shown here:
ddmmmyyyy,
ddmmmyyyy,
ddmmmyyyy,
ddmmmyyyy,
hh:mm:ss.mmmuuu
hh:mm:ss.mmmuuu
hh:mm:ss.mmmuuu
hh:mm:ss.mmmuuu
LCT
GMT
Cold Load (LCT)
SYSGEN (LCT)
dd
mmm
yyyy
hh
mm
ss
mmmuuu
LCT
Indicates that the date and time are shown in local civil time
GMT
Cold Load
(LCT)
Indicates the date and time of the most recent cold load
SYSGEN (LCT)
The SYSTIMES command applies only to the local system. To obtain the times
from a remote system, you must first start a TACL process there and then enter the
SYSTIMES command.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-222
U T IL S :T A C L C om m an d s a nd F u nctio ns
Example
To display the various system times, enter:
37> SYSTIMES
6 Aug 1992, 12:09:54.589512 LCT
6 Aug 1992, 20:09:54.589512 GMT
30 Jul 1992, 19:18:03.750427 Cold Load (LCT)
9 Jul 1992, 11:52:13.090000 SYSGEN (LCT)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-223
S Y S T IM E S C o m m a n d
U T IL S :T A C L C om m an d s a nd F u nctio ns
T A C L P ro gram
TACL Program
Enter the TACL program name to start a TACL process on your local system or on a
remote system (if your system is part of a network).
[\node-name.]TACL [ / run-option [ , run-option ] ... / ]
[ backup-cpu-num ] [ ; parameter [ , parameter ] ]
\node-name
is the name of the system on which TACL is to run. This parameter is valid only for
systems that have a node name (those that are part of a network). If you omit \
node-name, the TACL process runs on the system from which you issued the
TACL command.
run-option
is any of the options described in the RUN[D|V] Command on page 8-156.
backup-cpu-num
specifies the processor where the backup for the new TACL process is to run.
Specify backup-cpu-num as an integer in the range from 0 through 15. If you
omit this parameter, no backup process is created. You can specify a backup
process only if the TACL process is a named process (see the NAME option of the
RUN[D|V] Command on page 8-156).
parameter
is an operating parameter for the TACL process. It can be one of these:
ABENDONABEND
HOMETERM
PORTTACL
SEGVOL $volume-name
STOPONABEND
ABENDONABEND
specifies that this TACL process writes the message: TACL stopped by a
process ABEND/STOP to the current OUT file and terminates abnormally
(ABENDs) with an abend completion code when a child process (a process
started by this TACL process) terminates with no completion code or with an
abnormal completion code.
HOMETERM
specifies that TACL is to use the device specified by the TERM run-option as
the home terminal. If you omit HOMETERM, if the TACL IN file is the same as
the TACL OUT file, and if TACL is not in server mode, TACL uses its IN file
device as the home terminal, regardless of any specification by the TERM
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-224
U T IL S :T A C L C om m an d s a nd F u nctio ns
T A C L P ro gram
option. If the IN file is the same as the OUT file and the TACL process is not
named, TACL does not set its home terminal.
A process started by TACL inherits its home terminal unless the RUN
command that initiates the process specifies a different home terminal.
PORTTACL
specifies that the TACL being started is a port TACL (for example, a modem
port for a dial-in line or an X25 connection).
When using this parameter, the #SETCONFIGURATION option
STOPONFEMODEMERR should be ON. The default setting for the
#SETCONFIGURATION option STOPONFEMODEMERR is OFF.
The relationship between PORTTACL and STOPONFEMODEMERR is
summarized in this table.
PORTTACL
STOPONFEMODEMERR
Outcome
Specified
ON
Specified
OFF
Absent
ON
Absent
OFF
To start a TACL with the PORTTACL parameter, you must have a group ID
of 255, regardless of the setting of the TACL configuration parameter
STOPONFEMODEMERR. If your group ID is not 255, the TACL process
terminates abnormally (ABENDs). It is the responsibility of the super-group
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-225
U T IL S :T A C L C om m an d s a nd F u nctio ns
T A C L P ro gram
If a backup CPU was specified for the TACL process being started with the
PORTTACL startup option and the primary TACL fails, the backup TACL
process inherits the PORTTACL setting from the primary TACL process.
The PORTTACL startup parameter is only valid as a TACL process startup
parameter option. It is not a valid LOGON parameter option.
If a TACL process is not the process controlling modem port access, it
does not receive disconnect or error messages from the port modem,
including error 140 (STOPONFEMODEMERR). It is the responsibility of
the process that controls port access and receives messages from the port
modem to process appropriately disconnect and error messages, including
message140.
If both TACL and $CMON processes are configured for modem port
connections and the STOPONFEERROR option is enabled, ensure that
the $CMON program can appropriately process the PORTTACL parameter
for TACL process startup.
Caution. If a port is accessed only by means of a TACL process (that is, there is no Safeguard
or other type of port access control) a potential system security breach exists unless the
PORTTACL option is specified and STOPONFEMODEMERR is set to ON.
In the case where the TACL process stops, a user can then start a TACL process, under the
users control. In the cases where the TACL process continues to run in the logged-on state,
and the connection is resumed, any user can access the TACL process without logging on and
assume the identity of the original user.
SEGVOL $volume-name
specifies the name of a volume to be used by your extended segment, which
holds the TACL process variables. The default is the volume that contains the
default subvolume of the user who is logging on to the TACL.
STOPONABEND
specifies that this TACL process sends the message TACL stopped by a
process ABEND/STOP to the current OUT file and terminates normally
with a normal completion code when a subordinate process (a process
started by this TACL process) terminates with no completion code or with
an abnormal completion code.
Considerations
If you start a TACL process with the STOPONABEND option and specify a backup
CPU for the TACL process, and if the CPU fails, the new primary TACL process
initializes itself as if you had just logged on to it. The new process inherits the
STOPONABEND setting and reprocesses the IN file.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-226
U T IL S :T A C L C om m an d s a nd F u nctio ns
T A C L P ro gram
To run TACL as a server process, set the IN file to $RECEIVE. For more
information, see the TACL Programming Guide.
If the IN file is the same as the OUT file and the TACL process is not named, TACL
does not set its home terminal.
When using the ABENDONABEND and STOPONABEND parameters:
If a TACL process is configured with either ABENDONABEND or STOPONABEND:
If a child process is started in a different processor and that processor fails, the
TACL process assumes the subordinate process has terminated abnormally
and executes accordingly.
If a child process or process pair is started with the NOWAIT option and
terminates, the TACL process displays any error message it may have
received from the child process but continues to execute.
If the JOBID of the of the stopping process is the same as that of the stopped
process, the TACL process executes accordingly. It stops.
If the JOBID of the of the stopping process is different from that of the stopped
process or 0, the TACL process does not execute accordingly. Instead, it
terminates abnormally (ABENDs).
If a TACL process is started as a system load process pair and also controls a
modem port and the primary process fails, when the backup process takes
over, it inherits the STOPONABEND or ABENDONABEND setting. This
takeover process reprocesses the IN file and begins execution in the logged-off
state.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-227
U T IL S :T A C L C om m an d s a nd F u nctio ns
T A C L P ro gram
U T IL S :T A C L C om m an d s a nd F u nctio ns
T A C L P ro gram
0
Z^PROCNAME(0)
ZOFFSET(0:0)
82
ZLEN(0:0)
20
Z^FLAGS(0:0)
1
Z^RESERVED(0:2) 1 1 0
Z^DATA(0)
BYTE(0:111)
\PRUNE.$MP:150608489
Examples
1. This example shows how to start an interactive TACL process from an existing
TACL process:
13> TACL / IN $term1, OUT $term1, CPU 2, PRI 150, NOWAIT,&
13> &NAME $C106 / 3
After you enter this command:
A new TACL process starts; it accepts commands from, and displays its output
on, terminal $TERM1.
The name of the new TACL process is $C106.
The primary TACL process for $TERM1 is running in processor 2. The backup
process is running in processor 3.
The execution priority of the new process is 150.
Because the NOWAIT option was used, you can immediately execute another
command from the current TACL without waiting for the new TACL process to
terminate.
2. This example shows how to start a TACL process that uses a command file for
input:
14> TACL / IN comfile, OUT listing, NOWAIT /
After you enter this command:
A new TACL process executes the commands contained in the file COMFILE.
Output from the new TACL process is sent to the file LISTING.
The NOWAIT option means that control of the terminal returns to the original
TACL process while the new TACL process runs. You can now enter new
commands.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-229
U T IL S :T A C L C om m an d s a nd F u nctio ns
T IM E C o m m a n d
TIME Command
Use the TIME command to display the current setting of the system date and time-ofday clock in the format:
mmm dd, yyyy, hh:mm:ss
TIME
Considerations
The year is the 4-digit calendar year, from 1975 through 9999.
You can execute a TIME command without having logged on (with the LOGON
command) to a system.
Examples
If you are logged on, the TIME command displays:
88> TIME
July 9, 2002 15:57:39
If you are logged off, the TIME command uses a slightly different format:
90> TIME
09 JULY 2002, 15:59
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-230
U T IL S :T A C L C om m an d s a nd F u nctio ns
USE Command
The USE command defines the list of directories (in the built-in variable #USELIST)
that your TACL searches to find existing variables if they are not in your home
directory.
USE [ directory-name [ [,] directory-name ] ... ]
directory-name
is the name of an existing variable level of type DIRECTORY. If omitted, the use list
is set to:
:, :UTILS, :UTILS:TACL
Considerations
When you invoke a name, TACL first searches the home directory for a variable of
that name, and then in #USELIST. If these searches are unsuccessful, TACL
searches #PMSEARCHLIST for a macro or program file of that name.
The USE command ensures that your use list always includes the directories : (the
root), :UTILS, and :UTILS:TACL. If you omit any of these directories in your
arguments to USE, TACL automatically appends them to the use list in the order
shown. Access to, and operation of, TACL commands depends on their presence.
Directories are put into #USELIST in the order in which they are specified.
The list set by this command can be displayed with the ENV command.
You can save and restore the use list by pushing and popping #USELIST.
If you detach a segment contained in the current use list or a pushed use list, the
directory is removed from the use list.
The use list can contain up to 100 directories.
Example
13> USE MYDIR
14> ENV
Home :MYDIR.1
Pmsearch $MYVOL.MINE, $SYSTEM.SYSTEM
System \MYSYS
Use :MYDIR.1, :, :UTILS.1, :UTILS.1:TACL.1
Volume \MYSYS.$WORK.PROJECT, "NUNU"
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-231
U T IL S :T A C L C om m an d s a nd F u nctio ns
U S E R S P ro gram
USERS Program
Use the USERS program to list user attributes for a particular user or range of users.
USERS [ / run-option [ , run-option ] ... / ] [ range ]
run-option
is any of the options described in the RUN[D|V] Command on page 156.
range
specifies a particular user or group of users to be listed. Note that range refers to
the local system only. The allowable range specifications and their meanings are:
(blank)
lists current user only.
group-id,user-id
lists user with specified user number.
group-id,*
lists all users in specified group.
group-name.user-name
lists named user only.
[group-name.]*
lists all users in named group. If you omit group-name, USERS,lists users in
your group.
*,* or *.*
lists all users.
Examples
1. To display the USERS listing for yourself (the currently logged-on user), enter:
13> USERS
2. To find out the user name associated with the user ID 8,44, enter:
14> USERS 8,44
The USERS program displays information such as this:
GROUP USER I.D. # SECURITY DEFAULT VOLUMEID
MANUF .FRED 008,044 NUNU $BIG.BAD
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-232
U T IL S :T A C L C om m an d s a nd F u nctio ns
U S E R S P ro gram
3. You can get this information for all users in the PARTS group by entering:
15> USERS PARTS.*
GROUP USER I.D. # SECURITY DEFAULT VOLUMEID
PARTS
PARTS
PARTS
PARTS
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-233
U T IL S :T A C L C om m an d s a nd F u nctio ns
V A R IA B LE S C o m m a n d
VARIABLES Command
Use the VARIABLES command to display the names of all variables in a directory.
VARIABLES [ directory-name ]
directory-name
is the name of an existing variable level of type DIRECTORY.
Considerations
Example
This example lists variables in the home directory:
39> VARIABLES
Directory :
*MYSEG NEWPTIME OLDPTIME PROCESSID
*UTILS _PROMPTER _TACLBASE_FILE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-234
U T IL S :T A C L C om m an d s a nd F u nctio ns
V A R IN F O C o m m a n d
VARINFO Command
Use the VARINFO command to display attribute information about one or more of your
variables.
VARINFO [ variable [ [,] variable ] ... ]
variable
is the name of an existing variable.
Considerations
If you omit variable, VARINFO displays information about all variables in your
home directory.
VARINFO displays information similar to this:
Variable L/D Type Frm Mode File Process
MYDIR 1/1 DIRECTORY 0 SHARED $V1.SV2.FILE3
Variable
indicates the name of the variable.
L/D L
indicates the specific level of a variable about which you want information; D
(depth) indicates the total number of levels. Type indicates the type of variable
(directory, text, and so on).
Frm
indicates the frame number in which the variable level being examined was
created.
Mode
indicates different types of status of a variable depending on whether it is
associated with #REQUESTER or #SERVER, or with a segment:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-235
U T IL S :T A C L C om m an d s a nd F u nctio ns
V A R IN F O C o m m a n d
PRIVATE SHARED
File
is the name of #SERVER or the file opened by #REQUESTER. In the case of a
segment, it is the name of the segment file with which the variable is
associated.
Process
is the process associated with an implicit #SERVER; that is, the process that
started with INV, OUTV, or STATUS specifying the variable.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-236
U T IL S :T A C L C om m an d s a nd F u nctio ns
V A R T O F ILE C o m m a n d
VARTOFILE Command
Use the VARTOFILE command to copy the data in a variable to a file.
VARTOFILE variable-level file-name
variable-level
is the name of an existing variable level from which data is to be copied. It must not
be a DIRECTORY, a STRUCT, or a STRUCT item.
file-name
is the name of the file that is to receive the copy. If the file exists, it must be of a
type that can be written to by the sequential I/O (SIO) facility. The new data is
appended to the existing data. If the file does not exist, TACL creates an editformat file.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-237
U T IL S :T A C L C om m an d s a nd F u nctio ns
VCHANGE Command
Use the VCHANGE command to change all occurrences of one string to another string
in a range of lines within a variable.
VCHANGE [ / option [ , option ] ... / ] variable-level
string-1 string-2 [ range ]
option
is any of these:
OUT file-name
QUIET
TO variable-level
OUT file-name
specifies a device, or a sequential file accessible to the sequential I/O (SIO)
facility, that is to receive the changed lines. The listing includes line numbers. If
you omit this option, TACL writes the listing to its current OUT file. If the QUIET
option is present, this option is ignored.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
QUIET
suppresses listing of changed lines, even if the OUT option is supplied.
TO variable-level
is the name of an existing variable level to which a listing of all changed lines is
to be appended. Line numbers are not included. The QUIET option has no
affect on this option.
variable-level
is the name of an existing variable level containing the lines to be changed. It must
not be in a shared segment, and must not be a DIRECTORY, a STRUCT, or a
STRUCT item.
string-1
is the string to be changed wherever it occurs in the specified range of lines. A
string is the name of a variable level, text enclosed in quotation marks, or a
concatenation of such entities. The concatenation operator is '+' (the apostrophes
are required).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-238
U T IL S :T A C L C om m an d s a nd F u nctio ns
string-2
is the string that is to replace string-1.
range
specifies the line or lines in which the change is to occur. If you omit it, all lines are
included. A range specification can be any of these:
A
line-num
line-num / line-num
A
specifies all lines in the variable level.
line-num
specifies an individual line number. It can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies the last line in the variable level.
number
is a positive integer identifying a specific line.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-239
U T IL S :T A C L C om m an d s a nd F u nctio ns
Example
If these variables have the contents shown:
Var
Listvar
12345678910
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
Listvar
A QUICK BROWN
12345678910
11121314151617
A LAZY DOG
181920217
TWICE A DAY
A QUICK BROWN1
EXCEPT TUESDAYS
A LAZY DOG
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-240
U T IL S :T A C L C om m an d s a nd F u nctio ns
VC O PY Com m and
VCOPY Command
Use the VCOPY command to copy a range of lines from one variable and insert them
at a given line position in another variable.
VCOPY [ / option [ , option ] ... / ] source-var range
dest-var dest-line
option
is any of these:
OUT file-name
QUIET
TO variable-level
OUT file-name
specifies a device, or a sequential file accessible to the sequential I/O (SIO)
facility, that is to receive the copied lines. The listing includes line numbers. If
you omit this option, TACL writes the listing to its current OUT file. If the QUIET
option is present, this option is ignored.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
QUIET
suppresses listing of copied lines even if the OUT option is supplied.
TO variable-level
is the name of an existing variable level to which a listing of all copied lines is
to be appended. Line numbers are not included. The QUIET option has no
affect on this option.
source-var
is an existing variable level containing the lines to be copied. It must not be in a
shared segment, and must not be a DIRECTORY, a STRUCT, or a STRUCT item.
range
specifies the line or lines to be copied. A range specification can be any of these:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-241
U T IL S :T A C L C om m an d s a nd F u nctio ns
VC O PY Com m and
A
line-num
line-num / line-num
A
specifies all lines in the variable level.
line-num
specifies an individual line number. It can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies the last line in the variable level.
number
is an integer identifying a specific line.
dest-var
is an existing variable level that is to receive the copy. It must not be in a shared
segment, and must not be a DIRECTORY, a STRUCT, or a STRUCT item.
dest-line
specifies the line number in the destination variable level at which the copied lines
are to be inserted. This entry can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies a new line past the last line in the variable level.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-242
U T IL S :T A C L C om m an d s a nd F u nctio ns
VC O PY Com m and
number
is an integer identifying a specific line. It must be greater than zero and not
greater than the number of lines in the variable level, plus one (it can specify a
new line past the last existing line).
Considerations
Example
If these variables have the contents shown:
Srcvar
Dstvar
Listvar
ABCDEFG
12345678910
HIJKLMNOPQRST
1121314151617
UVWXYZ
18192021
TWICE A DAY
EXCEPT TUESDAYS
the command:
VCOPY /TO listvar/ srcvar 2/4 dstvar 3
causes them to contain:
Srcvar
Dstvar
Listvar
ABCDEFG
12345678910
HIJKLMNOPQRST
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
TWICE A DAY
UVWXYZ
TWICE A DAY
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-243
U T IL S :T A C L C om m an d s a nd F u nctio ns
VDELETE Command
Use the VDELETE command to delete a range of lines from a variable.
VDELETE [ / option [ , option ] / ... ] variable-level range
option
is any of these:
OUT file-name
QUIET
TO variable-level
OUT file-name
specifies a device, or a sequential file accessible to the sequential I/O (SIO)
facility, that is to receive the deleted lines. The listing includes line numbers. If
you omit this option, TACL writes the listing to its current OUT file. If the QUIET
option is present, this option is ignored.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
QUIET
suppresses listing of deleted lines even if the OUT option is supplied.
TO variable-level
is the name of an existing variable level to which a listing of all deleted lines is
to be appended. Line numbers are not included. The QUIET option has no
affect on this option.
variable-level
is an existing variable level from which lines are to be deleted. It must not be in a
shared segment, and must not be a DIRECTORY, a STRUCT, or a STRUCT item.
range
specifies the line or lines to be deleted. A range specification can be any of these:
A
line-num
line-num / line-num
A
specifies all lines in the variable level.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-244
U T IL S :T A C L C om m an d s a nd F u nctio ns
line-num
specifies an individual line number. It can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies the last line in the variable level.
number
is an integer identifying a specific line.
Example
If these variables have the contents shown:
Var
Listvar
12345678910
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
the command:
VDELETE /TO listvar/ var 2/4
causes them to contain:
Var
Listvar
12345678910
EXCEPT TUESDAYS
11121314151617
18192021
FOX JUMPED OVER
THE LAZY DOG
TWICE A DAY
U T IL S :T A C L C om m an d s a nd F u nctio ns
V F IN D C o m m a n d
VFIND Command
Use the VFIND command to find all lines containing occurrences of a specified string in
a range of lines within a variable.
VFIND [ / option [ , option ] / ... ] variable-level string
[ range ]
option
is any of these:
OUT file-name
QUIET
TO variable-level
OUT file-name
specifies a device, or a sequential file accessible to the sequential I/O (SIO)
facility, that is to receive the listing of lines in which string is found. The listing
includes line numbers. If you omit this option, TACL writes the listing to its
current OUT file. If the QUIET option is present, this option is ignored. If you
specify an OUT file that does not exist, TACL creates an EDIT file named listfile. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
QUIET
suppresses listing of lines in which string appeared even if the OUT option is
supplied.
TO variable-level
is the name of an existing variable level to which a listing is to be appended of
all lines in which string is found. Line numbers are not included. The QUIET
option has no affect on this option.
variable-level
is the name of an existing variable level in which the search is to be made. It must
not be in a shared segment, and must not be a DIRECTORY, a STRUCT, or a
STRUCT item.
string
is the string to be found. A string is the name of a variable level, text enclosed in
quotation marks, or a concatenation of such entities. The concatenation operator is
'+' (the apostrophes are required).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-246
U T IL S :T A C L C om m an d s a nd F u nctio ns
V F IN D C o m m a n d
range
specifies the line or lines in which the search is to be made. If you omit it, TACL
searches all lines. A range specification can be any of these:
A
line-num
line-num / line-num
A
specifies all lines in the variable level.
line-num
specifies an individual line number. It can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies the last line in the variable level.
number
is a positive integer identifying a specific line.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-247
U T IL S :T A C L C om m an d s a nd F u nctio ns
V F IN D C o m m a n d
Example
If these variables have the contents shown:
Var
Listvar
12345678910
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
the command:
VFIND /TO listvar/ var "THE" 1/4
causes them to contain:
Var
Listvar
12345678910
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-248
U T IL S :T A C L C om m an d s a nd F u nctio ns
V IN S E R T C o m m a n d
VINSERT Command
Use the VINSERT command to insert lines from the current TACL IN file into a given
line position in a variable.
VINSERT variable-level line-num
variable-level
is an existing variable level into which lines are to be inserted. It must not be in a
shared segment, and must not be a DIRECTORY, a STRUCT, or a STRUCT item.
line-num
specifies the line number at which lines are to be inserted. It can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies a new line past the last line in the variable level.
number
is an integer identifying a specific line. It must be greater than zero and not
greater than the number of lines in the variable level, plus one (it can specify a
new line past the last existing line).
Considerations
Inserted lines are placed just before the line specified by line-num.
If the input text contains TACL metacharacters, the setting of the #INFORMAT
built-in variable (for input to the IN file, including input to an interactive TACL
process) or the ?FORMAT Directive on page 5-6 (for text in TACL programs) can
affect how TACL interprets the string. For more information, see the #INFORMAT
Built-In Variable on page 9-196 or the ?FORMAT directive.
Example
If the variable VAR has the contents shown:
THE QUICK BROWN
FOX JUMPED OVER
THE LAZY DOG
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-249
U T IL S :T A C L C om m an d s a nd F u nctio ns
V IN S E R T C o m m a n d
TWICE A DAY
EXCEPT TUESDAYS.
the command:
VINSERT var 3
causes TACL to prompt with line numbers that the inserted lines will have in the
variable; TACL continues to accept lines until a line consisting solely of two slashes is
entered. The insertion can also be ended by CTRL-y.
In this dialog at the current IN file, TACL prompts with line numbers and the user
responds with text.
3 and over and
4 over and over
5 //
The variable then contains:
THE QUICK BROWN
FOX JUMPED OVER
and over and
over and over
THE LAZY DOG
TWICE A DAY
EXCEPT TUESDAYS.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-250
U T IL S :T A C L C om m an d s a nd F u nctio ns
V LIS T C o m m a n d
VLIST Command
Use the VLIST command to list a range of lines in a variable.
VLIST [ / option [ , option ] / ... ] variable-level
[ range ]
option
is any of these:
OUT file-name
QUIET
TO variable-level
OUT file-name
specifies a device, or a sequential file accessible to the sequential I/O (SIO)
facility, that is to receive the listing. The listing includes line numbers. If you
omit this option, TACL writes the listing to its current OUT file. If the QUIET
option is present, this option is ignored.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
QUIET
suppresses the listing, even if the OUT option is supplied.
TO variable-level
is the name of an existing variable level to which the listing is to be appended.
Line numbers are not included. The QUIET option has no affect on this option.
variable-level
is an existing variable level containing the lines to be listed. It must not be in a
shared segment, and must not be a DIRECTORY, a STRUCT, or a STRUCT item.
range
specifies the line or lines to be listed. If you omit it, all lines are listed. A range
specification can be any of these:
A
line-num
line-num / line-num
A
specifies an individual line number. It can be any of these:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-251
U T IL S :T A C L C om m an d s a nd F u nctio ns
V LIS T C o m m a n d
F
L
number
F
specifies the first line in the variable level.
L
specifies the last line in the variable level.
number
is an integer identifying a specific line.
Example
If these variables have the contents shown:
Var
Listvar
12345678910
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
the command:
VLIST /TO listvar/ var 2/4
causes them to contain:
Var
Listvar
12345678910
11121314151617
18192021
TWICE A DAY
EXCEPT TUESDAYS
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-252
U T IL S :T A C L C om m an d s a nd F u nctio ns
VM O VE Com m and
VMOVE Command
Use the VMOVE command to delete a range of lines from one variable and insert them
at a given line position in another variable.
VMOVE [ / option [ , option ] / ... ] source-var range
dest-var dest-line
option
is any of these:
OUT file-name
QUIET
TO variable-level
OUT file-name
specifies a device, or a sequential file accessible to the sequential I/O (SIO)
facility, that is to receive a listing of moved lines. The listing includes line
numbers of the new lines in the destination variable. If you omit this option,
TACL writes the listing to its current OUT file. If the QUIET option is present,
this option is ignored.
If you specify an OUT file that does not exist, TACL creates an EDIT file named
list-file. If you specify an OUT file that already exists, TACL appends the
information to the end of the file.
QUIET
suppresses listing of moved lines even if the OUT option is supplied.
TO variable-level
is the name of an existing variable level to which a listing of all moved lines is
to be appended. Line numbers are not included. The QUIET option has no
affect on this option.
source-var
is an existing variable level from which lines are to be deleted. It must not be in a
shared segment, and must not be a DIRECTORY, a STRUCT, or a STRUCT item.
range
specifies the line or lines to be moved. A range specification can be any of these:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-253
U T IL S :T A C L C om m an d s a nd F u nctio ns
VM O VE Com m and
A
line-num
line-num / line-num
A
specifies all lines in the variable level.
line-num
specifies an individual line number. It can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies the last line in the variable level.
number
is an integer identifying a specific line.
dest-var
is an existing variable level into which the moved lines are to be inserted. It must
not be in a shared segment, and must not be a DIRECTORY, a STRUCT, or a
STRUCT item.
dest-line
specifies the line number in the destination variable level at which the moved lines
are to be inserted. This entry can be any of these:
F
L
number
F
specifies the first line in the variable level.
L
specifies a new line past the last line in the variable level.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-254
U T IL S :T A C L C om m an d s a nd F u nctio ns
VM O VE Com m and
number
is an integer identifying a specific line. It must be greater than zero and not
greater than the number of lines in the variable level, plus one (it can specify a
new line past the last existing line).
Considerations
Example
If these variables have the contents shown:
Srcvar
Dstvar
Listvar
ABCDEFG
12345678910
HIJKLMNOPQRST
1121314151617
UVWXYZ
18192021
TWICE A DAY
EXCEPT
TUESDAYS
the command:
VMOVE /TO listvar/ srcvar 2/4 dstvar 3
causes them to contain:
Srcvar
Dstvar
Listvar
ABCDEFG
12345678910
EXCEPT
HIJKLMNOPQRST
1121314151617
TUESDAYS
18192021
TWICE A DAY
UVWXYZ
TWICE A DAY
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-255
U T IL S :T A C L C om m an d s a nd F u nctio ns
V O LU M E C o m m a n d
VOLUME Command
Use the VOLUME command to change temporarily your current settings for default
volume and subvolume or to return to your saved defaults.
VOLUME [ [\node-name.] volume ] [ , "security" ]
\node-name
specifies your default system. If you omit \ node-name, your default system does
not change.
volume
specifies your default volume and subvolume names. volume is one of these:
$volume-name
subvolume-name
$volume-name.subvolume-name
If you omit volume-name or subvolume-name, your logon default volume or
subvolume becomes the current default volume or subvolume.
"security"
sets your current default file security. The system assigns this file security to newly
created files unless you explicitly assign a different security when you create the
file. Specify security as a four-character string rwep to specify the security for
each type of file access: read, write, execute, and purge. For rwep you can
specify A, G, O, N, C, or U. For more information about file security, see the File
Utility Program (FUP) Reference Manual.
Considerations
Settings made with the VOLUME command are in effect only temporarily-until you
enter a LOGON command or a SYSTEM or VOLUME command with no
parameters. For example, if you log on again, all your current defaults are reset to
the original logon default system, volume, subvolume, and security (or as you
specified in your last DEFAULT command).
If the current default system is a remote system, you cannot specify a new current
default volume name that has more than six characters after the dollar sign ($).
Likewise, you cannot specify a new default system with the SYSTEM command if
the current default volume name contains more than six characters after the dollar
sign ($).
Entering VOLUME with no parameters resets your current default system, volume,
subvolume, and security to the values in effect at logon, or as they were set with
your last DEFAULT command.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-256
U T IL S :T A C L C om m an d s a nd F u nctio ns
V O LU M E C o m m a n d
To display your logon default volume and subvolume names, and your logon
default security, enter the USERS program or use the WHO command.
The security designations are:
O (Owner)
Only the owner can access the file; the owner must be
logged onto the local system.
G (Group)
Anyone in the owners group can access the file; the user
must be logged onto the local system.
A (Anyone)
Any user can access the file; the user must be logged onto
the local system.
U (User)
Only the owner can access the file; the owner may be
logged onto the local system or a remote system.
C (Community)
Anyone in the owners group can access the file; the user
may be logged onto the local system or a remote system.
N (Network)
Any user can access the file; the user may be logged onto
the local system or a remote system.
The security designation - (allow access to the local super ID only) is not
permitted in a VOLUME command. Use #SET #PROCESSFILESECURITY
instead.
Examples
1. To change your current default subvolume to $MANUF.BILLS, enter:
14> VOLUME $MANUF.BILLS
15>
2. You can reestablish the default system, volume, and subvolume that were in effect
when you logged on (unless you subsequently changed your saved default setting
with the DEFAULT program) by entering:
14> VOLUME
15>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-257
U T IL S :T A C L C om m an d s a nd F u nctio ns
VTREE Command
Use the VTREE command to list the names of all the variables in a directory, and in
directories below it, and so on.
VTREE [ directory-name ]
Considerations
Example
This example is a sample VTREE listing:
40> VTREE
Directory :
MYSEG
MYVAR
ANOTHER^VAR
PROMPT^NEWPTIME
PROMPT^OLDPTIME
PROMPT^PROCESSID
UTILS
TACL
ACTIVATE
...
YBUSDOWN
^UTILS
A^UTIL
...
PROMPTER
_TACLBASE_FILE
41>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-258
U T IL S :T A C L C om m an d s a nd F u nctio ns
WAKEUP Command
You can use the WAKEUP command to set the TACL wakeup mode.
WAKEUP { ON | OFF }
ON
means that TACL is awakened (returned from the paused state) when any process
started by TACL is deleted.
OFF
means that TACL is awakened only when the latest process started by TACL is
deleted or when a process you designate in a PAUSE command is deleted. This is
the logon default setting.
Consideration
A process is deleted when it abends, terminates normally, or a CPU fails. You can also
delete a process by entering the STOP command. You can delete a TACL process with
the EXIT command.
Example
To wake up TACL and return control of the terminal to TACL whenever a process that
you started is deleted, enter:
26> WAKEUP ON
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-259
U T IL S :T A C L C om m an d s a nd F u nctio ns
W HO Com m and
WHO Command
Use the WHO command to display information about your current TACL process.
WHO
Considerations
The WHO command is useful for verifying your current defaults. For example, if
you are on a network and use the SYSTEM command to access another system,
you can issue a WHO command to check your defaults before you run programs or
purge files. Checking defaults helps you avoid errors such as running programs on
the wrong system or purging remote files instead of local files.
The WHO command displays the name of the current default system if it is
different from your local system.
If the user logs on with a user name or user ID, Logon name shows group.user
information. If the user logs on with an alias, Logon name shows alias
information. For pre-D30 software RVUs, Logon name shows nothing.
Example
User MANUF.FRED, at \ROME, uses the SYSTEM command to make \NAPLES his
current default system. When he enters WHO, this information is displayed:
12> WHO
Home terminal: $FRED
TACL process: \ROME.$C127
Primary CPU: 4 (TXP) Backup CPU: 5 (TXP)
Default Segment File: $DISK.#6726
Pages allocated: 8 Pages Maximum: 1024
Bytes Used: 10644 (0%) Bytes Maximum: 2097152
Current volume: $MORE.CHECK Current system: \NAPLES
Saved volume: $FRED.DATA
Userid: 8,44 Username: MANUF.FRED Security: "NUNU"
Default process: 4,167
or
12> WHO
Home terminal: $FRED
TACL process: \ROME.$C127
Primary CPU: 4 (TXP) Backup CPU: 5 (TXP)
Default Segment File: $DISK.#6726
Pages allocated: 8 Pages Maximum: 1024
Bytes Used: 10644 (0%) Bytes Maximum: 2097152
Current volume: $MORE.CHECK Current system: \NAPLES
Saved volume: $FRED.DATA
Userid: 8,44 Username: MANUF.FRED Security: "NUNU"
Default process: 4,167
Logon name: MYALIAS
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-260
U T IL S :T A C L C om m an d s a nd F u nctio ns
W HO Com m and
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-261
U T IL S :T A C L C om m an d s a nd F u nctio ns
X B U S D O W N /Y B U S D O W N C o m m an d (S u p er-G ro u p
O nly)
Example
In a four-processor system, a super-group user can bring down the X bus from
processor 1 to all other processors by entering:
13>
THE
THE
THE
THE
XBUSDOWN 1, -1
X BUS FROM CPU
X BUS FROM CPU
X BUS FROM CPU
X BUS FROM CPU
01
01
01
01
TO
TO
TO
TO
00
01
02
03
HAS
HAS
HAS
HAS
BEEN
BEEN
BEEN
BEEN
DOWNED.
DOWNED.
DOWNED.
DOWNED.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-262
U T IL S :T A C L C om m an d s a nd F u nctio ns
X B U S U P /Y B U S U P C o m m a n d (S u pe r-G ro up O nly)
Example
A super-group user can bring the Y bus back up from processor 1 to processor 2 by
entering:
15> YBUSUP 1,2
THE Y BUS FROM CPU 01 TO 02 HAS BEEN UPPED.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-263
U T IL S :T A C L C om m an d s a nd F u nctio ns
Considerations
If you enter nothing but !, TACL reexecutes the previous command (! is the same
as ! - 1).
If TACL cannot find a command that matches your specification, whether by
absolute history number, relative history number, or command text, it issues an
error message.
You must enter the ! command from the IN file (normally your home terminal); you
cannot include it in a macro, for example. Similarly, you cannot change ! to another
name with an ALIAS, nor can you program a function key to execute the !
command.
Examples
1. This example illustrates the use of the ! command to recall and reexecute the
coding at history number 5:
10> !5
10> OUTVAR edstat
STATUS *,PROG $SYSTEM.SYSTEM.TEDIT
2. This example shows the use of the ! command to reexecute the most recent
occurrence of a SET command:
11> !SET
11> SET VARIABLE edstat STATUS *,PROG $SYSTEM.SYSTEM.TEDIT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-264
U T IL S :T A C L C om m an d s a nd F u nctio ns
Q u estio n M a rk (? ) C o m m a n d
Considerations
If you enter a question mark (?) without an argument, TACL displays the previous
command (? is the same as ? - 1).
If TACL cannot find a command that matches your specification-whether by
absolute history number, relative history number, or command text-it issues an
error message.
You must enter the ? command from the IN file (normally your home terminal); you
cannot include it in a macro, for example. Similarly, you cannot change ? to
another name with an ALIAS, nor can you program a function key to execute the ?
command.
The ? command does not increment the history number in the TACL prompt.
Examples
1. In this example, the user first uses the ? command to determine what command
was issued at history number 5. The user then enters the ! command to reexecute
that command (OUTVAR edstat).
10> ?5
10> OUTVAR edstat
10> !5
STATUS *,PROG $SYSTEM.SYSTEM.TEDIT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-265
U T IL S :T A C L C om m an d s a nd F u nctio ns
Q u estio n M a rk (? ) C o m m a n d
2. This example shows the use of the ? command to see the most recent command
that started with the text string SET. The user then enters the ! command to
reexecute the last SET command.
11>
11>
11>
11>
?SET
SET VARIABLE edstat STATUS *,PROG $SYSTEM.SYSTEM.TEDIT
!SET
SET VARIABLE edstat STATUS *,PROG $SYSTEM.SYSTEM.TEDIT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
8-266
9
Built-In Functions and Variables
This section contains an alphabetic summary of all built-in functions and variables,
followed by descriptions, in alphabetic order, of the syntax for each built-in function and
built-in variable. Each description (where appropriate) contains:
Note. All examples in this section are based on the assumptions that the built-in variable
#INFORMAT has been set to TACL, which enables recognition and processing of the TACL
special characters ([ and ], for example); that the built-in variable #PMSEARCHLIST has been
set to include (at least) $SYSTEM.SYSTEM and the keyword #DEFAULTS, which enables the
use of implied RUN commands; and that the required TACL library files have been loaded into
memory.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-1
S u m m a ry o f B u ilt-In F un ction s
Description
#ABORTTRANSACTION Built-In
Function
#ACTIVATEPROCESS Built-In
Function
#ADDDSTTRANSITION Built-In
Function (Super-Group Only)
#ALTERPRIORITY Built-In
Function
#BEGINTRANSACTION Built-In
Function
#CHANGEUSER Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-2
S u m m a ry o f B u ilt-In F un ction s
Description
#COLDLOADTACL Built-In
Function
#COMPUTEJULIANDAYNO
Built-In Function
#COMPUTETIMESTAMP Built-In
Function
#COMPUTETRANSID Built-In
Function
#CONVERTPHANDLE Built-In
Function
#CONVERTPROCESSTIME
Built-In Function
#CONVERTTIMESTAMP Built-In
Function
Creates a file
#CREATEPROCESSNAME
Built-In Function
#DEBUGPROCESS Built-In
Function
Defines a variable
#DEFINEDELETE Built-In
Function
#DEFINEDELETEALL Built-In
Function
#DEFINENAMES Built-In
Function
#DEFINENEXTNAME Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-3
S u m m a ry o f B u ilt-In F un ction s
Description
#DEFINEREADATTR Built-In
Function
#DEFINERESTORE Built-In
Function
#DEFINESAVEWORK Built-In
Function
#DEFINESETATTR Built-In
Function
#DEFINESETLIKE Built-In
Function
#EMSADDSUBJECT Built-In
Function
#EMSADDSUBJECTV Built-In
Function
#ENDTRANSACTION Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-4
S u m m a ry o f B u ilt-In F un ction s
Description
#FILEGETLOCKINFO Built-In
FunctionO
#GETCONFIGURATION Built-In
Function
#GETPROCESSSTATE Built-In
Function
#INTERPRETJULIANDAYNO
Built-In Function
#INTERPRETTRANSID Built-In
Function
#JULIANTIMESTAMP Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-5
S u m m a ry o f B u ilt-In F un ction s
Description
#XLOADEDFILES Built-In
Function
#LOOKUPPROCESS Built-In
Function
#NEWPROCESS Built-In
Function
Starts a process
#NEXTFILENAME Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-6
S u m m a ry o f B u ilt-In F un ction s
Description
#PROCESSEXISTS Built-In
Function
#PROCESSINFO Built-In
Function
#PROCESSLAUNCH Built-In
Function
Starts a process
#PROCESSORSTATUS Built-In
Function
#PROCESSORTYPE Built-In
Function
Deletes a file
#ROUTINENAME Built-In
Function
#SEGMENTCONVERT Built-In
Function
#SEGMENTINFO Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-7
S u m m a ry o f B u ilt-In F un ction s
Description
#SEGMENTVERSION Built-In
Function
#SETCONFIGURATION Built-In
Function
#SETPROCESSSTATE Built-In
Function
#SETSYSTEMCLOCK Built-In
Function (Super-Group Only)
#SPIFORMATCLOSE Built-In
Function
Terminates a process
#SUSPENDPROCESS Built-In
Function
Suspends a process
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-8
Description
#SYSTEMNAME Built-In
Function
#SYSTEMNUMBER Built-In
Function
#TACLOPERATION Built-In
Function
#TACLVERSION Built-In
Function
#VARIABLEINFO Built-In
Function
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-9
Description
#ASSIGN Built-In
Variable
#BREAKMODE Built-In
Variable
#CHARACTERRULES
Built-In Variable
#DEFAULTS Built-In
Variable
#DEFINEMODE Built-In
Variable
#ERRORNUMBERS
Built-In Variable
#HELPKEY Built-In
Variable
#HIGHPIN Built-In
Variable
#HOME Built-In
Variable
#INFORMAT Built-In
Variable
#INPUTEOF Built-In
Variable
#INLINEECHO Built-In
Variable
#INLINEOUT Built-In
Variable
#INLINEPROCESS
Built-In Variable
#INLINETO Built-In
Variable
#INSPECT Built-In
Variable
#MYTERM Built-In
Variable
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-10
Description
#OUTFORMAT Built-In
Variable
#PARAM Built-In
Variable
#PMSEARCHLIST
Built-In Variable
#PMSG Built-In
Variable
#PREFIX Built-In
Variable
#PROMPT Built-In
Variable
#ROUTEPMSG Built-In
Variable
#TACLSECURITY
Built-In Variable
#TRACE Built-In
Variable
#USELIST Built-In
Variable
#WAKEUP Built-In
Variable
#WIDTH Built-In
Variable
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-11
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-12
#A B E N D B uilt-In F u nctio n
text
is text, 0 to 80 characters, to be included in the process deletion message. Leading
and trailing spaces are ignored.
Result
Considerations
Examples
1. In this macro, TACL terminates $TMP2 after starting it:
?SECTION job^mgr ROUTINE
#FRAME
#PUSH errpm
== Start $TMP2
FUP /NOWAIT, NAME $TMP2/
== Now stop $TMP2:
#OUTPUT Error occurred, abending $TMP2...
#SET errpm [#ABEND /COMPLETIONCODE 20, ERROR/ $TMP2]
#OUTPUT Diagnostics: errpm = [errpm]
#UNFRAME
2. This routine produces this output after loading and invoking job^mgr:
14> job^mgr
Error occurred, abending $TMP2...
Diagnostics: errpm = 0
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-13
#A B O R T T R A N S A C T IO N B uilt-In F u nctio n
ABENDED: $TMP2
CPU Time 0:00:00.018
Completion Code 20
Termination Info 2278
Subsystem
Result
#ABORTTRANSACTION returns zero if successful, or a file-system error indicating the
reason the operation failed.
Consideration
To commit the database changes associated with a transaction identifier, use the
#ENDTRANSACTION built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-14
# A C T IV A T E P R O C E S S B uilt-In F u nctio n
Result
#ACTIVATEPROCESS returns a nonzero integer if it is successful; otherwise, it returns
zero.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-15
Result
#ADDDSTTRANSITION returns a nonzero value if it is successful, zero otherwise.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-16
For D-series RVUs, manipulate the DST either interactively using the
ADDDSTTRANSITION TACL command or programmatically using the
ADDDSTTRANSITION Guardian procedure.
For G04.00 and earlier G-series RVUs, manipulate the DST either interactively
using the ADDDSTTRANSITION TACL command or the SCF ALTER
command for the Kernel Subsystem, or programmatically using the
ADDDSTTRANSITION Guardian procedure.
For more information about setting the input variable values when TABLE is
specified, refer to the description of the COMPUTETIMESTAMP procedure in the
Guardian Procedure Calls Reference Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-17
# A LT E R P R IO R IT Y B uilt-In F u nctio n
Result
#ALTERPRIORITY returns a nonzero integer if it is successful; otherwise, it returns
zero.
Considerations
#A P P E N D B uilt-In F u nctio n
Result
#APPEND returns nothing.
Considerations
The appended text always starts a new line; #APPEND cannot append text to an
existing line.
If text is a variable name in brackets, and that variable contains multiple lines,
enclose the entire function call in square brackets. Otherwise, TACL tries to
execute the second line.
Example
This text defines a variable called kingandi, and then appends Please read the
attached message to the initial text:
11> [#DEF kingandi TEXT |BODY|Attention managers]
12> #APPEND kingandi Please read the attached message
13> #OUTPUTV kingandi
Attention managers
Please read the attached message
14>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-19
#A P P E N D V B uilt-In F u nctio n
Result
#APPENDV returns nothing.
Considerations
Example
Assuming the home terminal name is $MINE, the following:
#PUSH sayterm termname
#SETV sayterm "My terminal is"
#SET termname [#MYTERM]
#APPENDV sayterm termname '+' " at this time."
causes SAYTERM to contain My terminal is $MINE at this time.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-20
# A R G U M E N T B uilt-In F u nctio n
# A R G U M E N T B uilt-In F u nctio n
TACL is using PLAIN format, TACL does not recognize square brackets as
metacharacters.
The identity of the alternative being tested can have an effect on the result of
the VALUE option. For example, if there is a variable FN and a file named FN,
the VALUE option would return different results depending on which type of
argument is expected.
alternative
can be any of these:
ASSIGN [ / SYNTAX / ]
matches an existing logical-unit name. The name must be terminated by a
standard TACL separator. The SYNTAX option specifies that any logical-unit
name is acceptable as long as it is formatted correctly.
ATTRIBUTENAME
matches a valid DEFINE attribute name as described in Section 5, Statements
and Programs. The name must be terminated by a standard TACL separator.
ATTRIBUTEVALUE
matches a valid DEFINE attribute value as described in Section 5, Statements
and Programs. The name must be terminated by a standard TACL separator.
CHARACTERS / char-option [ , char-option ] ... /
matches a contiguous sequence of characters starting at an arbitrary position
in the argument sequence.
char-option is either of these:
START num
specifies the start of the sequence of characters, in the range -1 to +32767.
-1 specifies the current position. Positive numbers specify absolute
character positions: Zero specifies the first character of the argument set
(the space following the routine name); higher numbers specify character
positions to the right of that. If you omit this option, the starting position
defaults to the current position.
WIDTH num
specifies the number of characters to process. If you omit this option, it
defaults to one. If the specified number of characters are found, the current
position moves to the point just beyond the last character processed. If the
portion of the argument beyond the starting point contains fewer characters
than specified by WIDTH, an error occurs.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-22
# A R G U M E N T B uilt-In F u nctio n
CLOSEPAREN
matches a closing parenthesis.
COMMA
matches a comma.
DEFINENAME
matches a valid DEFINE name as described in Section 5, Statements and
Programs. The name must be terminated by a standard TACL separator.
DEFINETEMPLATE
matches a valid DEFINE template as described in Section 5, Statements and
Programs. The name must be terminated by a standard TACL separator.
DEVICE [ / SYNTAX / ]
matches the name of an existing device. The SYNTAX option specifies that
any device name is acceptable as long as it is formatted correctly.
END
matches the closing square bracket, vertical line, or end-of-line (if the routine
invocation is not enclosed in square brackets) that marks the end of the
argument sequence.
FILENAME [ / file-option [ , file-option ] ... / ]
matches the name of an existing file or a DEFINE name that references an
existing file.
file-option can be either of these:
SEARCHLIST search-place [ search-place ] ...
specifies the locations to be searched for the named file.
search-place can be either of these:
subvol
specifies the subvolume to be searched.
#DEFAULTS
specifies that your current default subvolume is to be searched. Do not
use square brackets around #DEFAULTS.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-23
# A R G U M E N T B uilt-In F u nctio n
SYNTAX
specifies that any file name or DEFINE name is acceptable as long as it is
formatted correctly. The file need not exist. If you do not include SYNTAX
and you specify a file name, the file name returned by VALUE is fully
qualified, using your current defaults for any missing fields.
GMOMJOBID
matches a valid job ancestor job ID, expressed as one of these:
$process-name. num
cpu,pin, num
such as $XYZ.3 or 2,12,100. num is a positive integer. The value of pin can
range from 0 to 65535.
JOBID
matches a valid job ID expressed as a signed integer.
KEYWORD / WORDLIST keyword [ keyword ] ... /
matches any one of a specified list of words (WORDLIST is required; it must
precede the first keyword in the list).
NUMBER [ / range-option [ , range-option ] / ]
matches a number, the name of a variable that contains a numeric value, or an
arithmetic expression enclosed in parentheses. It also matches an argument
that begins with one or more numeric digits (0-9); if the argument also contains
nonnumeric data, the current position pointer stops immediately following the
last digit. The VALUE option obtains the value of the number.
range-option can be either of these:
MINIMUM num
specifies the minimum valid number. num is an integer.
MAXIMUM num
specifies the maximum valid number. num is an integer.
OPENPAREN
matches an opening parenthesis.
OTHERWISE
specifies that TACL should not invoke the TACL error handler when
#ARGUMENT detects an error (such as an invalid argument). Instead, TACL
allows that the program to handle the error. TACL does not move the pointer to
the current position argument and does not return the current argument. If you
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-24
# A R G U M E N T B uilt-In F u nctio n
# A R G U M E N T B uilt-In F u nctio n
STRING
matches the name of a variable level, text enclosed in quotation marks, or a
concatenation of such entities. The concatenation operator is '+'. With this type
of alternative, the TEXT option returns an exact copy of the string as it was
entered; the VALUE option returns the resulting value of the string after it has
been evaluated (enclosing quotation marks removed and all specified
invocation and concatenation performed).
SUBSYSTEM
matches a subsystem ID (for use with #STOP, #ABEND, or the Subsystem
Programmable Interface). See the TACL Programming Guide for a description
of subsystem IDs.
SUBVOL
matches the name of a subvolume.
SUBVOLTEMPLATE
matches a subvolume name that may contain special template characters.
SYSTEMNAME [ / SYNTAX / ]
matches the name of a known system. The SYNTAX option specifies that any
node name is acceptable as long as it is formatted correctly.
TEMPLATE
matches a file-name template. The template returned by VALUE has defaults
substituted for fields omitted in the input.
TEXT
matches all remaining arguments. The text returned by VALUE contains
spaces in place of end-of-line delimiters.
TOKEN / TOKEN token-text /
matches a user-specified character sequence regardless of delimiters. The
TOKEN keyword is required preceding the token text. The token text, 1 to 32
characters in length, is not case-sensitive. It cannot include a comma, left or
right parenthesis, semicolon, slash, or space.
TRANSID
matches a TMF transaction ID formatted as follows:
\node-name( crash-count). cpu. sequence
If crash-count is zero, the transaction ID can be formatted as follows:
\node-name. cpu. sequence
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-26
# A R G U M E N T B uilt-In F u nctio n
# A R G U M E N T B uilt-In F u nctio n
Result
#ARGUMENT returns the position number of the alternative that matches the type of
the routine argument being examined.
Considerations
Argument
Text
Value
Plain or quoted
sv+[fn]
sv+[fn]
SUBVOL.[fn]
TACL
sv+[fn}
sv+FILENAME
SUBVOL.FILENAME
Under control of PLAIN format, TACL does not recognize square brackets as
metacharacters, so does not invoke the variable. Under QUOTED format, the quotation
marks instruct TACL to treat the square brackets as ordinary text.
For arguments not affected by #INFORMAT, the TEXT and VALUE options behave in
the same way as shown for TACL input format.
The identity of the alternative being tested can have an effect on the result of the
VALUE option. For example, suppose that in addition to the variable FN, above,
there were a file of the same name. Using a single argument, the VALUE option
could return different results depending on which type of argument is expected;
examples of this are shown in Table 9-4 on page 9-29.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-28
# A R G U M E N T B uilt-In F u nctio n
Argument
Text
Value
String
fn
fn
FILENAME
Variable
fn
fn
:MYDIR:FN.1
Filename
fn
fn
\SYS.$VOL.SUBVOL.FN
Other special VALUE results are documented in the descriptions of the individual
alternatives. In the majority of cases, however, TEXT and VALUE results are the same.
As shown in the preceding table, a given argument can meet the criteria for more
than one alternative. When this occurs, TACL uses the first such alternative tested
and places its interpretation (if any) on the VALUE result. You should, therefore,
order the alternatives in an #ARGUMENT call so that the alternative that
corresponds to the type of argument most likely to be processed by #ARGUMENT
appears first in the alternatives list.
Examples
1. This example shows the use of #ARGUMENT to examine the argument list of a
routine.
#PUSH arg
[#LOOP |DO|
[#CASE [#ARGUMENT /VALUE arg/ FILENAME SUBVOL END]
| 1 | #OUTPUT Argument is existing file named [arg].
| 2 | #OUTPUT Argument is valid subvolume [arg].
| 3 | #OUTPUT No more arguments to parse.
] == End of case
|UNTIL| NOT [#MORE]
] == End of loop
2. This example shows how a STRING argument can be processed. Assume that
RTN is a routine defined as follows:
#FRAME
#PUSH txt vlu
== Get a string, using #IF to discard #ARGUMENT result
#IF [#ARGUMENT /TEXT txt, VALUE vlu/ STRING]
== Get end-of-args, using #IF to discard #ARGUMENT result
#IF [#ARGUMENT END]
== Show string as originally entered
#OUTPUTV "TEXT: " '+' txt
== Show string after evaluation and concatenation
#OUTPUTV "VALUE: " '+' vlu
#UNFRAME
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-29
# A R G U M E N T B uilt-In F u nctio n
Assume also that the variable TERMNAME contains the name of the home terminal,
which currently is $MINE, and that RTN is invoked as follows:
RTN "My terminal is " '+' termname '+' " at this time."
The resulting output is:
TEXT: "My terminal is " '+' termname '+' " at this time."
VALUE: My terminal is $MINE at this time.
For additional examples, see the TACL Programming Guide.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-30
# A S S IG N B u ilt-In V a ria b le
# A S S IG N B u ilt-In V a ria b le
specifies the logical-unit name about which you want information. For more
information about logical units, see the ASSIGN Command on page 8-21.
Result
#ASSIGN returns as its result a space-separated list of the requested information
about the specified logical unit. If you do not specify any options, #ASSIGN returns a
space-separated list of all currently defined logical units.
Considerations
If you use #SET #ASSIGN without any arguments, all logical units become
undefined.
If you supply only a logical-unit name, that logical unit becomes undefined.
When you supply both a logical-unit name and options, the logical unit
definition is set according to the options; any previous definition of the logical
unit is lost.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-32
# A S S IG N B u ilt-In V a ria b le
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-33
# B A C K U P C P U B uilt-In F u nctio n
Result
#BACKUPCPU returns nothing.
Considerations
#BACKUPCPU with no CPU specification has no effect if the current TACL process
has no backup. If there is a backup, TACL deletes it.
Your TACL must be a named process to have a backup.
The specified CPU module must exist on your system.
The backup CPU cannot be the same as the primary CPU of your TACL.
The backup CPU need not be running at the time that #BACKUPCPU is issued.
If you specify a CPU for a backup process and a backup process already exists in
any CPU, an error message appears.
TACL switches to the backup process if the primary CPU becomes unavailable.
After the primary CPU is reloaded, TACL switches back to the primary CPU unless
a user is logged on, in which case TACL postpones switching until the user logs
off.
To force TACL to switch to the backup process, see the #SWITCH Built-In Function
on page 9-395.
For examples, see the BACKUPCPU Command on page 8-28.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-34
# B E G IN T R A N S A C T IO N B uilt-In F u nctio n
Result
#BEGINTRANSACTION returns zero if it is successful, or a file-system error indicating
the reason it failed.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-35
# B R E A K M O D E B u ilt-In V a ria b le
Result
#BREAKMODE returns the current break mode setting: DISABLE, ENABLE, or
POSTPONE.
Considerations
Use #PUSH #BREAKMODE (or PUSH #BREAKMODE) to save the current break
mode setting.
Use #SET #BREAKMODE (or SET VARIABLE #BREAKMODE) to establish a new
break mode setting.
The syntax for #SET #BREAKMODE is:
#SET #BREAKMODE { DISABLE | ENABLE | POSTPONE }
DISABLE
immediately turns off the BREAK key. Pressing the key has no further effect,
nor is control of the key given to another process. If the previous break mode
was POSTPONE and someone had pressed the BREAK key, TACL discards
the postponed break.
ENABLE
immediately turns on the BREAK key; TACL takes control of the key without
noting whether control had been taken by another process. If the previous
break mode was POSTPONE and someone had pressed the BREAK key, the
postponed break immediately takes effect as though the key had just been
pressed.
POSTPONE
turns on the BREAK key until someone presses the key once. After the key is
pressed, TACL turns off the BREAK key; further breaks have no effect. Control
of the BREAK key is not given to another process. If the previous break mode
was POSTPONE and someone had pressed the BREAK key, TACL discards
the postponed break. If there is active I/O on IN or OUT when BREAK is
pressed the final time before it is turned off, that I/O operation is retried.
Use #POP #BREAKMODE (or POP #BREAKMODE) to restore the break mode to
its previous setting.
When you first log on, #BREAKMODE is initialized to ENABLE.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-36
#B R E A K P O IN T B uilt-In F u nctio n
Result
#BREAKPOINT returns the previous breakpoint state of the variable level: 0 if there
was no breakpoint, -1 if there was one.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-37
#B U IL T IN S B uilt-In F u nctio n
Result
#BUILTINS returns a space-separated list of the names of the specified built-in
functions or variables.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-38
# C A S E B uilt-In F u nctio n
Result
#CASE returns all option text that follows a selected label; the text is terminated by the
next label or the end of the enclosure. The result includes any spaces or carriage
returns that precede the text. If text does not match any label, #CASE returns the text
following the OTHERWISE label, up to the next label or to the end of the enclosure.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-39
# C A S E B uilt-In F u nctio n
Examples
1. This macro accepts an argument. If the argument is 0, the macro writes Zero; if the
argument is 1, the macro writes One, and so on.
[#CASE %1%
| 0 | #OUTPUT
| 1 | #OUTPUT
| 2 | #OUTPUT
| 3 | #OUTPUT
| 4 | #OUTPUT
| 5 | #OUTPUT
| 6 | #OUTPUT
| 7 | #OUTPUT
| 8 | #OUTPUT
| 9 | #OUTPUT
| OTHERWISE |
]
Zero
One
Two
Three
Four
Five
Six
Seven
Eight
Nine
#OUTPUT %1% is not a digit.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-40
# C H A N G E U S E R B uilt-In F u nctio n
#CHANGEUSER [ / CHANGEDEFAULTS / ]
group-name.user-name | group-iduser-id | alias} password
CHANGEDEFAULTS
causes TACL to set its default node, volume, subvolume, and file security to that of
the new user instead of retaining the current users values.
group-name. user-name or group-id, user-id
is the group name and user name, or the group number and user number, of the
user who is logging on. The user identity must already have been established. If
you do not have a user account, see your system administrator.
If the TACL configuration NAMELOGON option is not set to 0, or if Safeguard is
running and the Safeguard NAMELOGON flag is not set to 0 (for the
USER_AUTHENTICATE_call), the group number and user number is not
accepted.
alias
is an alternate assigned name. Each alias must be unique within the local system.
An alias is a case-sensitive text string that can be up to 32 alphanumeric
characters in length. In addition to alphabetic and numeric characters, the
characters period (.), hyphen (-), and underscore(_) are permitted within the text
string. The first character of an alias must be alphabetic or numeric. For more
information on aliases, see the Safeguard Reference Manual.
password
is the password associated with the user.
Result
#CHANGEUSER returns -1 if it is successful; if not, it returns 0.
Considerations
# C H A N G E U S E R B uilt-In F u nctio n
If the user ID and password are syntactically correct (but not necessarily valid),
TACL sends a pre-LOGON message to $CMON (if that user-supplied monitoring
process exists) for additional validation before calling VERIFYUSER. In addition,
TACL sends LOGON messages to $CMON during the logon process. For more
information about $CMON, see Section 6, The TACL Environment.
If the logon operation is rejected, either by the USER_AUTHENTICATE_
procedure or by $CMON, TACL notifies you of the failure but does not specify
whether user-name or password was wrong.
If the USER_AUTHENTICATE_ procedure fails to recognize the user information
given during the logon operation, the TACL built-in variable #ERRORNUMBERS
contains the error information. To display the error information, issue these
commands:
#PUSH n1 n2 n3 n4
#SETMANY n1 n2 n3 n4, [#ERRORNUMBERS]
where:
n1
n2
n3
n4
=
=
=
=
TACL sends an illegal LOGON message (code -53) to $CMON on the third and
all subsequent logon failures until a logon succeeds. Each time it sends the illegal
LOGON message, TACL displays the $CMON reply (if not empty). Safeguard and
USER_AUTHENTICATE_ security logic can impose a delay before the next
prompt. You cannot exit from the delay by pressing the BREAK key.
Both the LOGON command (issued while you are already logged on) and the
#CHANGEUSER built-in function change your identity while keeping your previous
IDs, variables, segment files, and so on. The principal difference is that with
LOGON you assume both the saved (logon) default subvolume and the current
default subvolume of the new ID; with #CHANGEUSER, you assume the saved
default subvolume of the new ID, but remain in the subvolume that was current at
the time you invoked the function.
You can configure TACL to disable logons from a logged-on state. To alter the
configuration, CMON should reply with the NOCHANGEUSER field set to -1. For
more information, see the Guardian Programmers Guide. If the capability is
disabled, #CHANGEUSER fails and returns a zero. To display the value of
NOCHANGEUSER, use #GETCONFIGURATION.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-42
# C H A N G E U S E R B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-43
#C H A R A C T E R R U L E S B u ilt-In V a ria b le
Result
#CHARACTERRULES returns the fully qualified name of the file containing the
character-processing rules currently in effect. This name is CPRULES0, CPRULES1,
or the name of a user-supplied file that contains character rules.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-44
#C H A R A C T E R R U L E S B u ilt-In V a ria b le
If an error occurs while acquiring the new rules, the character rules already in
effect remain unchanged.
If a #SET #CHARACTERRULES is never executed, TACL uses default rules.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-45
#C H A R A D D R B uilt-In F u nctio n
Result
#CHARADDR returns the address of the first character of the specified line.
Considerations
Example
Assume that var is a variable level containing these characters:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
The invocation:
#CHARADDR var 2
returns 9; the letter H at the beginning of line 2 is the ninth character in var, counting
the end-of-line between lines 1 and 2 as one character.
The invocation:
#CHARADDR var 100
returns 30: the 26 characters, three end-of-line characters, plus one.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-46
# C H A R B R E A K B uilt-In F u nctio n
Result
#CHARBREAK returns nothing.
Considerations
Each line break contains an internal end-of-line character that counts as one byte.
#CHARBREAK inserts the end-of-line immediately preceding the existing character
at char-addr.
The end-of-line is inserted regardless of whether there is already an end-of-line at
char-addr.
If char-addr is 1, an end-of-line is inserted at the beginning of the variable level.
If char-addr is beyond the end of the variable level, no end-of-line is inserted.
IF char-addr is less than 1, an error occurs.
Example
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
The invocation:
#CHARBREAK var 13
causes var to contain:
ABCDEFG
HIJK
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-47
# C H A R B R E A K B uilt-In F u nctio n
LMNOPQRST
UVWXYZ
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-48
#C H A R C O U N T B uilt-In F u nctio n
Result
#CHARCOUNT returns the number of characters in the variable level, counting each
end-of-line except the last as a character and counting each internal representation of
[, |, or ] as multiple characters.
Considerations
To make a quoted string yield the same character count as a variable level
containing the same text (minus the quotation marks), the final end-of-line in a
variable level is not counted. This means that #CHARCOUNT does not necessarily
yield the same result as #VARIABLEINFO /OCCURS/, which includes all end-oflines in its count.
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
1. Assume that var is a variable level containing:
ABCDEFG
The invocation:
#CHARCOUNT var
returns 7; #CHARCOUNT does not count the last end-of-line character in a
variable level as a character.
2. Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
The invocation:
#CHARCOUNT var
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-49
#C H A R C O U N T B uilt-In F u nctio n
returns 28; there are 26 letters and 2 internal line breaks. #CHARCOUNT does not
count the last end-of-line character.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-50
#C H A R D E L B uilt-In F u nctio n
Result
#CHARDEL returns nothing.
Considerations
If you use TO, the character specified by char-addr-2 is included in the deletion.
That is, x TO y is equivalent to x FOR (y-x+1).
If you use TO and char-addr-1 is greater than char-addr-2, or if you use FOR
and char-count is zero, no deletion occurs.
If you omit both FOR and TO, TACL deletes the character specified by charaddr-1.
Any part of the specified deletion that lies beyond the end of the variable level is
ignored.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-51
#C H A R D E L B uilt-In F u nctio n
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing the following, including one internal endof-line character after each line:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. Either of the invocations:
#CHARDEL var 7 TO 9 or #CHARDEL var 7 FOR 3
causes var to contain:
ABCDEFIJKLMNOPQRST
UVWXYZ
2. Either of the invocations:
#CHARDEL var 7 TO 100 or #CHARDEL var 7 FOR 94
causes var to contain:
ABCDEF
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-52
# C H A R F IN D B uilt-In F u nctio n
Result
#CHARFIND returns the character address at which text begins. If text is not found,
#CHARFIND returns zero.
Considerations
If char-addr is past the end of the variable level, #CHARFIND returns zero.
A text specification can include internal end-of-line characters if the entire
invocation is enclosed in square brackets, but leading and trailing end-of-lines and
spaces are ignored.
The search begins immediately at the character address specified. If you make
repeated calls to this function, using the result of each as a starting point for the
next, you must add one to that result before supplying it to a subsequent call.
If variable-level is empty, #CHARFIND returns zero.
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-53
# C H A R F IN D B uilt-In F u nctio n
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. The invocation:
#CHARFIND var 1 IJK
returns 10; the first occurrence of IJK starting at or after 1 is at character address
10.
2. The invocation:
#CHARFIND var 10 IJK
returns 10; the first occurrence of IJK is exactly at the starting character address,
10.
3. The invocation:
#CHARFIND var 11 IJK
returns 0; there are no occurrences of IJK starting at or after character address 11.
4. The invocation:
#CHARFIND var 1 FOO
returns 0; there are no occurrences of FOO anywhere in var.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-54
#C H A R F IN D R B uilt-In F u nctio n
Result
#CHARFINDR returns the character address at which text begins. If text is not found,
#CHARFINDR returns zero.
Considerations
If char-addr is past the end of the variable level, #CHARFINDR starts the search
at the end of the contents of the variable.
A text specification can include internal end-of-line characters if the entire
invocation is enclosed in square brackets, but leading and trailing end-of-lines and
spaces are ignored.
The search begins immediately at the character address specified. Because the
search does not find a match unless the entire matching text appears at or before
char-addr, you must specify a starting address at the end of a variable level
(#CHARCOUNT or greater) to find text at the end of it.
If variable-level is empty, then #CHARFINDR returns zero.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-55
#C H A R F IN D R B uilt-In F u nctio n
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. The invocation:
#CHARFINDR var 28 IJK
returns 10; the nearest occurrence of IJK ending before character address 28
starts at character address 10.
2. The invocation:
#CHARFINDR var 14 IJK
returns 10; the nearest occurrence of IJK ending before character address 14
starts at character address 10.
3. The invocation:
#CHARFINDR var 12 IJK
returns 10.
4. The invocation:
#CHARFINDR var 28 FOO
returns 0; there are no occurrences of FOO anywhere in var.
5. This set of statements returns 3:
#PUSH x
#SET x ABCDEFG
#CHARFINDR x [#CHARCOUNT x] C
The occurrence of C is three characters from the start of the contents of variable x.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-56
#C H A R F IN D R V B uilt-In F u nctio n
Result
#CHARFINDRV returns the character address at which string begins. If string is not
found, #CHARFINDRV returns zero.
Considerations
If char-addr is past the end of the variable level, #CHARFINDRV starts the
search at the end of the contents of the variable.
The trailing end-of-line in string is ignored. Leading and trailing spaces are
preserved, as are all other end-of-lines.
The search begins immediately at the character address specified. Because the
search does not find a match unless the entire matching text appears at or before
char-addr, you must specify a starting address beyond the end of a variable
level ([#CHARCOUNT] or greater) to find text at the end of it.
If variable-level is empty, then #CHARFINDRV returns zero.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-57
#C H A R F IN D R V B uilt-In F u nctio n
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
and that var2 is a variable level containing:
IJK
1. Either of the invocations:
#CHARFINDRV var 28 "IJK" or #CHARFINDRV var 28 var2
returns 10; the nearest occurrence of IJK ending before character address 28
starts at character address 10.
2. Either of the invocations:
#CHARFINDRV var 11 "IJK" or #CHARFINDRV var 11 var2
returns 0; although an occurrence of IJK starts at character address 10, it does not
end before or at character address 12.
3. The invocation:
#CHARFINDRV var 28 "FOO"
returns 0; there are no occurrences of FOO anywhere in var.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-58
# C H A R F IN D V B uilt-In F u nctio n
Result
#CHARFINDV returns the character address at which string-2 begins. If string-2
is not found, #CHARFINDV returns zero.
Considerations
If char-addr is past the end of the variable level, #CHARFINDV returns zero.
The search begins immediately at the character address specified. If you make
repeated calls to this function, using the result of each as a starting point for the
next, you must add one to that result before supplying it to a subsequent call.
If string-1 is empty, #CHARFINDV returns zero.
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-59
# C H A R F IN D V B uilt-In F u nctio n
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
and that var2 is a variable level containing:
IJK
1. Either of the invocations:
#CHARFINDV var 1 "IJK" or #CHARFINDV var 1 var2
returns 10; the first occurrence of IJK starting at or after 1 is at character address
10.
2. Either of the invocations:
#CHARFINDV var 10 "IJK" or #CHARFINDV var 10 var2
returns 10; the first occurrence of IJK is exactly at the starting character address,
10.
3. Either of the invocations:
#CHARFINDV var 11 "IJK" or #CHARFINDV var 11 var2
returns 0; there are no occurrences of IJK starting at or after character address 11.
4. The invocation:
#CHARFINDV var 1 "FOO"
returns 0; there are no occurrences of FOO anywhere in var.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-60
# C H A R G E T B uilt-In F u nctio n
Result
#CHARGET returns the copied characters.
Considerations
If you use TO, the character specified by char-addr-2 is included in the copy:
That is, x TO y is equivalent to x FOR (y-x)+1.
If you use TO and char-addr-1 is greater than or equal to char-addr-2, or if
you use FOR and char-count is less than one, no copying occurs.
If you omit both FOR and TO, one character is copied.
If char-addr-1 is less than 1, an error occurs.
If any part of the specified copy lies beyond the end of the variable level, that part
is ignored.
If the result of #CHARGET might possibly include one or more internal end-oflines, you must enclose in square brackets the invocation of the function that
obtains that result.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-61
# C H A R G E T B uilt-In F u nctio n
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. Either of the invocations:
#CHARGET var 2 TO 4 or #CHARGET var 2 FOR 3
returns:
BCD
2. The invocation:
#CHARGET var 3 FOR 10
returns:
CDEFG
HIJK
and therefore the function invocation producing that result must be enclosed in
square brackets:
[#OUTPUT [#CHARGET var 3 FOR 10]]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-62
# C H A R G E T V B uilt-In F u nctio n
Result
#CHARGETV returns nothing.
Considerations
If you use TO, the character specified by char-addr-2 is included in the copy:
That is, x TO y is equivalent to x FOR (y-x)+1.
If you use TO and char-addr-1 is greater than or equal to char-addr-2, or if
you use FOR and char-count is less than one, no copying occurs.
If you omit both FOR and TO, one character is copied.
If char-addr-1 is less than 1, an error occurs.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-63
# C H A R G E T V B uilt-In F u nctio n
Any part of the specified copy that lies beyond the end of var-1 is ignored.
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. Either of the invocations:
#CHARGETV var var2 2 TO 4 or #CHARGETV var var2 2 FOR 3
set var2 to:
BCD
2. The invocation:
#CHARGETV var var2 3 FOR 10
sets var2 to:
CDEFG
HIJK
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-64
# C H A R IN S B uilt-In F u nctio n
Result
#CHARINS returns nothing.
Considerations
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-65
1. The invocation:
#CHARINS var 13 NEW TEXT
causes var to contain:
ABCDEFG
HIJKNEW TEXTLMNOPQRST
UVWXYZ
2. The invocation:
[#CHARINS var 13 NEW TEXT]
causes var to contain:
ABCDEFG
HIJKNEW
TEXTLMNOPQRST
UVWXYZ
3. The invocation:
#CHARINS var 100 NEW TEXT
causes var to contain:
ABCDEFG
HIJKLMNOPQRST
UVWXYZNEW TEXT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-66
# C H A R IN S B uilt-In F u nctio n
# C H A R IN S V B uilt-In F u nctio n
Result
#CHARINSV returns nothing.
Considerations
The trailing end-of-line in string is suppressed. Leading and trailing spaces are
preserved, as are all other end-of-lines.
If char-addr is beyond the end of the variable level, the string is concatenated
with the last line in the variable level.
Each logical line contains an end-of-line character that counts as one byte. For
variables that contain TACL statements, each metacharacter uses the number of
visible characters plus one, including unprintable characters that are subject to
change from one TACL RVU to another. Nonmetacharacters use one byte.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-67
# C H A R IN S V B uilt-In F u nctio n
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
and that var2 is a variable level containing:
NEW
TEXT
1. The invocation:
#CHARINSV var 13 var2
causes var to contain:
ABCDEFG
HIJKNEW
TEXTLMNOPQRST
UVWXYZ
2. The invocation:
#CHARINSV var 13 "NEW TEXT"
causes var to contain:
ABCDEFG
HIJKNEW TEXTLMNOPQRST
UVWXYZ
3. The invocation:
#CHARINSV var 100 "NEW TEXT"
causes var to contain:
ABCDEFG
HIJKLMNOPQRST
UVWXYZNEW TEXT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-68
# C O L D LO A D T A C L B uilt-In F u nctio n
Result
#COLDLOADTACL returns -1 if the TACL process from which it was invoked is the first
TACL process started during the cold-load process, and the TACL process has not
logged off since it was started. Otherwise, #COLDLOADTACL returns zero.
Consideration
#COLDLOADTACL is used primarily by TACLBASE, which performs certain operations
when it is invoked by the cold-load TACL process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-69
# C O M P A R E V B uilt-In F u nctio n
Result
#COMPAREV returns a nonzero value if the contents of the two arguments are the
same; it returns zero if they are different.
Considerations
Example
1. This example shows how a variable level can be compared with quoted text.
#PUSH termname term_is_mine
#SET termname [#MYTERM]
2. This example returns a nonzero value if #MYTERM is "$MINE".
#SET term_is_mine [#COMPAREV termname "$MINE"]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-70
#C O M P U T E B uilt-In F u nctio n
Result
Consideration
#COMPUTE performs integer arithmetic; consequently, it discards any fractional part
resulting from division. For example, #COMPUTE 2 / 3 yields a zero result.
Example
1. This routine computes the sum of two numbers:
?SECTION compute^nums ROUTINE
#FRAME
#PUSH a b c
#SETMANY a b, 1 2
#SET c [#COMPUTE a + b]
#OUTPUTV c
2. The routine produces this output:
12> compute^nums
3
13>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-71
Result
#COMPUTEJULIANDAYNO returns a space-separated list of four numbers. The first
number is the Julian day number. If an error occurs, TACL sets the first number to -1.
The remaining three numbers are error flags that indicate range errors in the three
arguments. A flag is 0 if its matching argument (year, month, or day) is within the range
for the date element it specifies, or -1 if it is outside the range.
Considerations
Specifying 14 for the month or 87 for the day, for example, causes
#COMPUTEJULIANDAYNO to return a range error in the flag representing that
argument. Specifying 31 for a 30-day month or February 29 in a year other than a
leap year, for example, causes range errors for both month and day because
#COMPUTEJULIANDAYNO is unable to determine which field is actually in error.
For examples showing the use of time functions, see the TACL Programming
Guide.
Example
This example shows #COMPUTEJULIANDAYNO output:
29> #OUTPUT [#COMPUTEJULIANDAYNO 1994 3 31]
2449078 0 0 0
This example shows #COMPUTEJULIANDAYNO error output:
30> #OUTPUT [#COMPUTEJULIANDAYNO 1993 4 65]
-1 0 0 -1
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-72
# C O M P U T E T IM E S T A M P B uilt-In F u nctio n
Result
#COMPUTETIMESTAMP returns a space-separated list of nine numbers. The first
number is the four-word timestamp. If an error occurs, TACL sets the first number to -1.
The other eight numbers are error flags that indicate range errors in the arguments. An
error flag is 0 if its matching argument is within the range for the date/time element it
specifies, or -1 if it is outside the range.
Example
This example shows #COMPUTETIMESTAMP output:
29> #OUTPUT [#COMPUTETIMESTAMP 1992 3 31 15 37 50 273 146]
211568816270273146 0 0 0 0 0 0 0 0
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-73
#C O M P U T E T R A N S ID B uilt-In F u nctio n
Result
#COMPUTETRANSID returns a numeric status code indicating the outcome of the
conversion:
Code
Condition
-4
Invalid system
-3
-2
Invalid CPU
-1
Invalid sequence
Successful conversion
Any other value indicates a TACL problem; contact your service provider.
If the status code is zero, the numeric transaction ID follows the status code, separated
by a space.
Consideration
Use the #INTERPRETTRANSID built-in function to convert a numeric transaction ID to
separate numeric values for the components of the transaction ID.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-74
#C O N T IM E B uilt-In F u nctio n
Result
#CONTIME returns seven numbers representing various components of date and time
(year, month, day, hour, minute, second, hundredths of a second), as shown in the
following examples.
Examples
1. Assuming #INFORMAT is set to TACL, this example illustrates the use of
#CONTIME with #TIMESTAMP:
14> #OUTPUT [#CONTIME [#TIMESTAMP]] 1992 06 27 9 28 16 16
2. This code shows how portions of a timestamp can be extracted and used to create
a file name that includes the month and day the file was created:
#PUSH date month list
#SETMANY _ month date, [#CONTIME [#TIMESTAMP]]
#CHARINSV date 1 month == Insert mm before dd in date
VARTOFILE list TEMP[date] == Output to a file named TEMPmmdd
If, for example, the date were June 10, this code would create a file named
TEMP0610.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-75
# C O N V E R T P H A N D LE B uilt-In F u nctio n
Results
If you specify PROCESSID, #CONVERTPHANDLE returns a process name for the
specified integer sequence. If the process is not named, TACL returns the CPU and
PIN. The node name is always included. If the specified process handle is not valid,
TACL returns an error.
If you specify INTEGERS, #CONVERTPHANDLE returns a process handle,
represented as ten integers. If the process does not exist, a null process handle,
consisting of the value 65535 in each of the ten integers, is returned.
Considerations
Process handles are the D-series successor to process identifiers (CRTPIDs) for
process-control purposes. Process handles can occur in SPI buffers and in operating
system messages. TACL provides a process handle in the TACL structure
:_COMPLETION^PROCDEATH for completion handling on D-series systems.
Note. The format for a process handle is defined by as part of the TACL software product and
is subject to change in future RVUs.
Use the external format of a process handle (ten integers separated by periods) if you
need to present a process handle to TACL in external form, as in calls to #SSPUT and
#SET.
Examples
1. This function call converts a ten-integer process handle to its corresponding
process identifier:
10> #CONVERTPHANDLE/PROCESSID/ 512.31.2.18.0.0.11.57728.0.243
\SYS2.$S
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-76
# C O N V E R T P H A N D LE B uilt-In F u nctio n
2. This function call converts a process name to its corresponding process handle:
11> #CONVERTPHANDLE / INTEGERS / $S
512.31.2.18.0.0.11.57728.0.243
3. This example uses #CONVERTPHANDLE to convert a process handle field in
STRUCT s to a process identifier:
[#CONVERTPHANDLE / PROCESSID / [s:proc]]
where
proc
[s:proc]
[#CONVERTPHANDLE
/PROCESSID/ [s:p]]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-77
#C O N V E R T P R O C E S S T IM E B uilt-In F u nctio n
Result
#CONVERTPROCESSTIME returns a space-separated list of the equivalent number
of hours, minutes, seconds, milliseconds, and microseconds in the process-time
argument.
Example
Assuming #INFORMAT is set to TACL, this example converts the value (in
microseconds) obtained by the PROCESSTIME option of #PROCESSINFO:
19> #OUTPUT [#CONVERTPROCESSTIME [#PROCESSINFO
/PROCESSTIME/]]
0 0 4 122 58
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-78
# C O N V E R T T IM E S T A M P B uilt-In F u nctio n
Conversion
LCT to GMT
LST to GMT
\node-name
is the name of the system where conversion is to be done.
Result
#CONVERTTIMESTAMP returns a numeric error code. If the conversion is successful,
the error code (zero) is followed by a space and the converted timestamp.
The codes are:
Code
Condition
-2
Impossible LCT
-1
Ambiguous LCT
>2
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-79
# C O N V E R T T IM E S T A M P B uilt-In F u nctio n
Example
This example obtains the current Greenwich mean time, converts the timestamp to
local civil time (LCT), and displays the GMT and LCT in component form:
?SECTION convtime ROUTINE
#FRAME
#PUSH gmttime, loctime, err
#SET gmttime [#JULIANTIMESTAMP]
#SETMANY err loctime , [#CONVERTTIMESTAMP gmttime 0]
SINK [IF [err] |THEN|
#OUTPUT Error occurred: [err]
|ELSE|
#OUTPUT GMT = [#INTERPRETTIMESTAMP gmttime]
#OUTPUT LCT = [#INTERPRETTIMESTAMP loctime]
]
#UNFRAME
When the preceding routine is invoked, TACL displays:
GMT = 2448713 1992 3 31 0 53 47 174 708
LCT = 2448712 1992 3 30 16 53 47 174 708
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-80
num
the number of data pages allocated for the primary and all secondary extents.
For format 1 files, specify num as an integer in the range from 1 through
65535.
For format 2 files, specify num as an integer in the range from 1 through
512000000.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-81
If a logical volume is specified in the file name for file creation, the physical
volume on which the file is created is chosen by the system. The physicalvolume parameter overrides this selection.
The PHYSICALVOLUME option should be used only if no physical volume is
specified in file-name. Otherwise, a file-system error is returned.
Result
#CREATEFILE returns zero if it is successful; otherwise, it returns a file-system error
indicating the reason for the failure.
Considerations
If you specify only the volume for the filename, a temporary file is created on
the specified volume. You should also specify the FILENAMEV to retrieve the
temporary file name.
The PHYSICALVOLUME option should be used only if a logical volume was
specified for the filename. Otherwise a file-system error is returned.
If the system does not support the PHYSICALVOLUME option, error 561 is
returned.
Various failures on a system with a DSM/Storage Manager might result in the
inaccessibility of a logical file.
Example
#CREATEFILE /EXTENT 2,PHYSICALVOLUME $mg/ $v.a.b
Specifies that logical file, $v.s.f, be created with a two-page extent size on physical
volume $mg.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-82
# C R E A T E P R O C E S S N A M E B uilt-In F u nctio n
Result
#CREATEPROCESSNAME returns a unique, unused process name in one of the
forms $Xnnn, $Ynnn, or $Zxxx, where n is any numeric character and x is any
alphanumeric character.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-83
# C R E A T E R E M O T E N A M E B uilt-In F u nctio n
Result
#CREATEREMOTENAME returns a unique, unused process name in one of the forms
$Xnnn, $Ynnn, or $Zxxx, where n is any numeric character and x is any alphanumeric
character. If \node-name does not exist, TACL returns an error. If \node-name is the
name of the local system, #CREATEREMOTENAME returns a process name for the
local system.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-84
#D E B U G P R O C E S S B uilt-In F u nctio n
Result
#DEBUGPROCESS returns zero if it is successful; otherwise, it returns the error code
returned by the call to the DEBUGPROCESS procedure.
Considerations
If you are not a super-group member or a group manager, you can debug only
those processes whose process accessor ID matches your user ID; you must have
read access to the program file.
If you are a group manager, you can debug any process whose process accessor
ID matches any user ID in your group; you must have read access to the program
file.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-85
#D E B U G P R O C E S S B uilt-In F u nctio n
If you are the super ID, you can debug any process. Only the super ID can debug
privileged processes.
The process to be debugged does not enter the debug state until it executes its
next instruction in the user code space; the process cannot enter the debug state
while executing system code. If you enter the NOW option, however, the process
enters the debug state immediately. To use this option, you must have a group ID
of 255.
To set or obtain the current value of the INSPECT flag, which determines the
default debugger, use the #INSPECT built-in function.
H-Series Usage
The program DEBUG is not available for use on systems running H-series software.
The DEBUG command invokes a debugger, it can be Inspect, Native Inspect
(eInspect, which is not in the family of Inspect debuggers), or Visual Inspect.
The rules about which debugger gets invoked are approximately the same as for the
RUND command. That is, if the INSPECT attribute is set ON anywhere (in the object
file during compilation, or on the TACL command line using the SET command), you
will get a debugger in the Inspect family (either Inspect or VI), unless of course neither
of these debuggers is available, and then you get the default debugger, eInspect. If
the Inspect attribute is OFF, you get Native Inspect (eInspect).
Inspect is invoked only for TNS accelerated/interpreted programs (never for TNS/E
native programs), while Visual Inspect can handle both of these. Native Inspect
handles only TNS/E native programs and snapshots.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-86
# D E F B uilt-In F u nctio n
# D E F B uilt-In F u nctio n
PRIVATE
specifies that the creator of the segment file has read and write access to
the file and that no other process may open it.
SHARED
specifies that the segment file is a read-only file and that other processes
may open it for read access.
file-name
is the name of a TACL segment file. If file-name does not exist, TACL
creates it and initializes it as an empty TACL segment.
STRUCT structure-body
specifies that variable represents a structure.
structure-body
is a set of declarations for data, substructures, FILLER bytes, or redefinitions,
as described in Section 4, Variables. All internal square brackets in the body
are expanded before the structure is declared.
Result
#DEF returns nothing.
Considerations
If you specify a segment file in a DIRECTORY definition, the segment file must
reside on the local system (where the TACL process is executing).
If the #DEF declaration contains a |BODY| label, it must be enclosed in square
brackets. For a DIRECTORY or STRUCT definition, square brackets are required
only if the entire #DEF cannot be contained in one line and you prefer not to use
the ampersand (&) continuation character.
The |BODY| label, used in the enclosure that defines ordinary variables, is not
used in a DIRECTORY or STRUCT definition.
#DEF does not always behave exactly the same as a #PUSH-#SET combination:
For example, #SET A BB[CCC]DDDD invokes [CCC] to obtain the contents of the
variable level CCC before assigning the result to the variable level A. On the other
hand, [#DEF A type |BODY| BB[CCC]DDDD] assigns the value BB[CCC]DDDD to
A, including the brackets, leaving the expansion to be done when A is invoked.
This may cause unexpected results, especially if type is DELTA.
Do not try to use #DEF on the root directory (:). If you try this, TACL returns
*ERROR* Cannot push or pop the root segment's root. In addition, to avoid losing
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-88
# D E F B uilt-In F u nctio n
standard functionality from your TACL environment, do not use #DEF on the
directories supplied as part of the TACL software product (such as UTILS).
Examples
1. This example defines a variable, RTN, as a ROUTINE that accepts no arguments
and displays a thank you message:
[#DEF rtn ROUTINE
|BODY|
SINK [#ARGUMENT END]
#OUTPUT Thank you!
]
2. The next example sets up the alias P for the PERUSE command:
[#DEF p ALIAS
|BODY|
PERUSE
]
3. These examples declare structures:
[#DEF inventory STRUCT
BEGIN
INT item;
INT price;
INT quantity;
END;
]
[#DEF obsolete^stuff STRUCT
LIKE inventory;
]
4. This examples define directories:
PURGE segfl
#DEF :myseg DIRECTORY PRIVATE segfl
#DIR :our^seg DIRECTORY SHARED $system.segs.segfile
#DEF :dir DIRECTORY
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-89
# D E F A U LT S B u ilt-In V a ria b le
Result
#DEFAULTS returns the file-name defaults you request. If you specify both options, the
defaults appear in a space-separated list in the order in which you presented the
requests. If you omit both options, #DEFAULTS returns the current defaults.
Considerations
When you first log on, #DEFAULTS is initialized to your saved default volume and
subvolume (current default and saved default are the same at this time).
Use #PUSH #DEFAULTS (or PUSH #DEFAULTS) to save a copy of your current
file-name defaults.
Use #POP #DEFAULTS (or POP #DEFAULTS) to replace your current file-name
defaults with the previously pushed defaults.
Use #SET #DEFAULTS (or SET VARIABLE #DEFAULTS) to assign your current
defaults to a specified subvolume.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-90
# D E F A U LT S B u ilt-In V a ria b le
Example
Assuming #INFORMAT is set to TACL, this example displays both your current and
saved defaults:
12> #OUTPUT [ #DEFAULTS /SAVED, CURRENT/ ]
$BUNK.HOUSE $OPEN.RANGE
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-91
# D E F IN E A D D B uilt-In F u nctio n
Result
#DEFINEADD returns a numeric error code indicating the outcome of the DEFINEADD
procedure; zero indicates success. See Appendix B, Error Messages for a list of
DEFINE-oriented error codes.
Consideration
When a backup TACL process takes over, TACL deletes existing assignments.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-92
#D E F IN E D E LE T E B uilt-In F u nctio n
Result
#DEFINEDELETE returns a numeric error code indicating the outcome of the
DEFINEDELETE procedure. Zero indicates success. See Appendix B, Error Messages
for a list of DEFINE-oriented error codes. If an error occurs, the DEFINE is not deleted.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-93
# D E F IN E D E L E T E A L L B uilt-In F u nctio n
Result
#DEFINEDELETEALL returns a numeric error code indicating the outcome of the
DEFINEDELETEALL procedure; zero indicates success. See Appendix B, Error
Messages for DEFINE-oriented error codes.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-94
#D E F IN E IN F O B uilt-In F u nctio n
Result
#DEFINEINFO returns a numeric error code indicating the outcome of the
DEFINEINFO procedure; zero indicates success. See Appendix B, Error Messages for
a list of DEFINE-oriented error codes.
If the error code is 0, the following are also included as a space-separated list:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-95
#D E F IN E M O D E B u ilt-In V a ria b le
Result
#DEFINEMODE returns the current DEFMODE setting: OFF or ON.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-96
# D E F IN E N A M E S B uilt-In F u nctio n
Result
#DEFINENAMES returns a (possibly empty) space-separated list of all DEFINE names
that match the DEFINE template.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-97
# D E F IN E N E X T N A M E B uilt-In F u nctio n
Result
#DEFINENEXTNAME returns a numeric error code indicating the outcome of the
DEFINENEXTNAME procedure; zero indicates success. See Appendix B, Error
Messages for a list of DEFINE-oriented error codes.
If the error code is 0, it is followed by a space and the name of the next DEFINE in
sequence.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-98
# D E F IN E R E A D A T T R B uilt-In F u nctio n
Search present attributes, plus required and optional attributes not present
Result
#DEFINEREADATTR returns a numeric error code indicating the outcome of the
DEFINEREADATTR procedure; zero indicates success. See Appendix B, Error
Messages for a list of DEFINE-oriented error codes.
If the error code is 0 or 2061 (no more attributes), the following are also included as a
space-separated list:
The cursor value for the next attribute in sequence, consistent with the mode
specification. This is zero if an attribute name, rather than a cursor, was supplied
as an argument.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-99
# D E F IN E R E A D A T T R B uilt-In F u nctio n
Consideration
An error code of 2061 can be considered as indicating a successful operation, but if
you are using a loop to read successive attributes, receipt of the no more attributes
code should be a signal to terminate the loop.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-100
#D E F IN E R E S T O R E B uilt-In F u nctio n
Result
#DEFINERESTORE returns a space-separated list consisting of a numeric error code,
the name of the saved DEFINE, and a numeric consistency-check result. Error codes
are listed in Appendix B; zero indicates a successful operation. Consistency-check
numbers are shown in Table 8-7 on page 8-185; zero indicates no consistency errors.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-101
#D E F IN E R E S T O R E B uilt-In F u nctio n
However, the saved DEFINE is restored to the working set even if it is incomplete,
inconsistent, or invalid.
If you save the =_DEFAULTS DEFINE, you must use the REPLACE option when
restoring it. Because the =_DEFAULTS DEFINE always exists, it cannot be added.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-102
# D E F IN E R E S T O R E W O R K B uilt-In F u nctio n
Result
#DEFINERESTOREWORK returns a numeric error code indicating the outcome of the
DEFINERESTOREWORK procedure; zero indicates success. See Appendix B, Error
Messages for DEFINE-oriented error codes.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-103
# D E F IN E S A V E B uilt-In F u nctio n
Result
#DEFINESAVE returns a numeric error code, a space, and the number of bytes
required to save the DEFINE. The error codes are:
Code
Condition
No error
2049
2051
2052
2053
2054
2066
Parameter missing
2076
2077
If the error code is any of the above except zero, the DEFINE is not saved.
These codes are warnings only, and are used only when the working set is being
saved; it is saved even if one of the following appears.
Code
Condition
2057
2058
2059
# D E F IN E S A V E B uilt-In F u nctio n
Considerations
The internal form of the DEFINE is placed in the buffer if it is large enough to hold
it.
If the buffer is too small, an error occurs; you can use the length field of the result
to determine how large the buffer should have been. The following are estimates of
the maximum buffer size needed for each DEFINE class:
Class
Estimated Size
CATALOG
202 bytes
DEFAULTS
2300 bytes
MAP
118 bytes
SORT
740 bytes
SPOOL
274 bytes
SUBSORT
226 bytes
TAPE
392 bytes
If the buffer is larger than the DEFINE, the unused portion of the buffer contains
unpredictable data.
You should not modify the data in the buffer in any way; if it is modified,
#DEFINERESTORE might not be able to restore it.
If the working set is to be saved, the DEFINE name can be that of an active
DEFINE; the working set is saved regardless.
The working set can be saved even if it is inconsistent, invalid, or incomplete; an
appropriate error is indicated in the result, however.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-105
# D E F IN E S A V E W O R K B uilt-In F u nctio n
Result
#DEFINESAVEWORK returns a numeric error code indicating the outcome of the
DEFINESAVEWORK procedure; zero indicates success. See Appendix B, Error
Messages for a list of DEFINE-oriented error codes.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-106
#D E F IN E S E T A T T R B uilt-In F u nctio n
Result
#DEFINESETATTR returns a numeric error code indicating the outcome of the
DEFINESETATTR procedure; zero indicates success. See Appendix B, Error
Messages for a list of DEFINE-oriented error codes.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-107
#D E F IN E S E T L IK E B uilt-In F u nctio n
Result
#DEFINESETLIKE returns a numeric error code indicating the outcome of the
DEFINESETLIKE procedure; zero indicates success. See Appendix B, Error Messages
for a list of DEFINE-oriented error codes.
Consideration
#DEFINESETLIKE deletes existing attribute values in the working set. You can save
attributes in the background set by using #DEFINESAVEWORK before invoking this
function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-108
Result
#DEFINEVALIDATEWORK returns a numeric error code indicating the outcome of the
DEFINEVALIDATEWORK procedure, followed by a space and a check number. If the
error code is 0, the working set is consistent. See Appendix B, Error Messages for a
list of DEFINE-oriented error codes.
The check number is 0 unless the error code is 2058 (working set is inconsistent), in
which case the code value depends on the DEFINE class. See Table 8-7 on
page 8-185 for a list of check numbers.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-109
# D E L A Y B uilt-In F u nctio n
Result
#DELAY returns nothing.
Consideration
You cannot end the #DELAY built-in function using the BREAK key if you specify
#BREAKMODE DISABLE or #BREAKMODE POSTPONE. You can end the
#DELAY built-in function using the BREAK key only when #BREAKMODE
ENABLE is specified.
If I/O is pending or outstanding on a TACL IN file, you cannot break the delay.
Examples
This list illustrates #DELAY values:
#DELAY 100
#DELAY 6000
#DELAY 30000
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-110
#D E LT A B uilt-In F u nctio n
Result
#DELTA returns whatever is left in the #DELTA buffer after editing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-111
#D E LT A B uilt-In F u nctio n
In the examples that will be given, CTRL-y is not shown (it does not appear on your
terminal). However, because the system responds to a CTRL-y with EOF!, wherever
you see EOF! in an example you can assume that CTRL-y was entered at that point.
For example:
6> #DELTA
#DELTA 7>
#DELTA 7>
This is a
#DELTA 8>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-112
#D E LT A B uilt-In F u nctio n
Comments
Comments help to produce readable #DELTA code. A #DELTA comment is an
exclamation point (!) followed, optionally, by explanatory text to the end of the line. You
can also use the standard TACL { } and == comments within #DELTA. (Using TACL
comments could be safer because #DELTA ignores all text within comments; you can
also continue them over additional lines by using ampersands. However, #DELTA
parses ! comments, so errors within those comments are possible.)
The Buffer
The main work area in #DELTA is a buffer that can contain up to 30,000 characters.
However, there could be fewer than 30,000 characters available because of ongoing
TACL activity. (At the time #DELTA exits, not more than 15,000 characters can remain
in the buffer or a Text buffer overflow error occurs.) Use the HT command to display
the contents of the buffer; for example:
10> [#DELTA These characters are the
10> contents of the buffer]
#DELTA 11> HT
#DELTA 11> EOF!
These characters are the
contents of the buffer
#DELTA provides ways of moving all or part of the buffer to or from files or variable
levels. All editing is done on the text in the buffer.
#DELTA does no character translation during file I/O or while accessing variable levels;
all data access is done in the PLAIN mode. For example, when #DELTA reads a file,
square brackets and vertical bars remain ordinary text; they do not become TACL
invocation characters. Comments are not eliminated, nor do ampersands function as
continuation characters.
When #DELTA reads a variable level containing a routine or a macro, special internal
character sequences appear in the buffer. In particular, a square bracket or vertical bar
appears as a pair of bytes, the second of which is the square bracket or vertical bar
(the first is RVU-dependent and subject to change); remember this point when
counting characters.
The Pointer
The pointer indicates your current position in the buffer. Some commands use the
pointer value; others modify the position of the pointer. The #DELTA pointer points
between characters. When you use a command that depends on the pointer value,
#DELTA operates on the characters relative to the pointer position.
You can display the current pointer value by entering a period followed by an equal
sign (.=). The V (view) command shows lines in the buffer and indicates by (.) the
position of the pointer within the buffer; for example:
14> #DELTA Test string
#DELTA 15> .=
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-113
#D E LT A B uilt-In F u nctio n
If you specify a range of text using an X register value with an empty Y register, the
range is the characters between the pointer position and x number of end-of-lines.
(EOLs) For example, 1T means type the rest of the current line (one EOL); 2T
means type the rest of the current line and the next line (two EOLs). A zero means
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-114
#D E LT A B uilt-In F u nctio n
the range between the current pointer position and the beginning of the current
line.
If you specify both X and Y register values, the range is the characters between
the absolute locations y and x. For example, 4,8T means type the characters
between the fourth character and eighth character in the buffer (this can include
end-of-line characters).
X Register Arithmetic
You can do mathematical operations on the contents of the X register. The available
operators are:
+n
Addition
-n
Subtraction
*n
Multiplication
/n
Division
FL
For example, these commands display the text from the current pointer position to the
character that is ten characters to the right of the current pointer position (note that the
first command simply displays the pointer location within the line):
#DELTA 24> v
#DELTA 24> EOF!
This is (.)a test string
#DELTA 25> .,.+10t
#DELTA 25> EOF!
a test str
Other examples of X register arithmetic are:
[#DEF zerofill DELTA |BODY|
0J == Jump to beginning of buffer.
6-Z,48I == Insert enough zeros to make 6 characters long.
] == End DEF
[#DEF truncate DELTA |BODY|
Z-79 ?G == If text is longer than 79 characters ...
79,ZK == ... delete excess characters.
'
] == End DEF
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-115
#D E LT A B uilt-In F u nctio n
#DELTA Commands
This subsection describes the commands that you can use in #DELTA. Table 9-5 is a
summary of all #DELTA commands.
Table 9-5. Summary of #DELTA Commands (page 1 of 2)
Command
Description
Moves X into Y
Displays X or Y,X
:?
Negative condition
Ends condition
<
Begins iteration
>
Ends iteration
^\
EI
EO
FC
@FC
FE
FF
FG
FL
FO
Pops a variable
FT
FU
Pushes a variable
#D E LT A B uilt-In F u nctio n
Description
Text manipulation
Variable control
File manipulation
#DELTA control
Many commands in #DELTA can be modified by the command flags. The command
flags are the at sign (@) and the colon (:). The meaning and use of the command flags
varies from command to command.
Description
Effect on Buffer
xC
Moves characters
P=P+x
x:C
Moves characters
with return code
xD
Deletes characters
x chars deleted
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-117
#D E LT A B uilt-In F u nctio n
Description
Effect on Buffer
xFC
Changes lines to
lowercase
Lines from P to x
EOLs changed to
lowercase
y,xFC
Changes characters
to lowercase
Chars y through x
changed to
lowercase
x@FC
Changes lines to
uppercase
Lines from P to x
EOLs changed to
uppercase
y,x@FC
Changes characters
to uppercase
Chars y through x
changed to
uppercase
Itext$ *
Inserts text
Text inserted at P
P = P + size
xI
Inserts ASCII
character
Character
inserted at P
P=P+1
y,xI
Inserts y*ASCII
characters
y number of
characters
inserted at P
P=P+y
xJ
Jump characters
P=x
xK
Kills lines
Lines from P to x
EOLs deleted
y,xK
Kills characters
Chars from y to x
deleted
P=y
xL
Moves pointer by
lines
P = x EOLs
xStext$ *
Searches
P = xth occurrence
x:Stext$ *
xT
Types lines
y,x T Types
chars
@Tvar$
:Ttext$ *
Types text
xV
Views lines
x:V
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-118
#D E LT A B uilt-In F u nctio n
Description
Effect on Buffer
Converts number in
text to value in X
X = (P)
x\
Puts x in text
Text value of x
inserted at P
P = P + size
* You can modify the I, S, and :T commands with the @ flag to change the text delimiter from $ to another
character; for example: @I/text/
Description
Effect On Buffer
FEvar$
X = -1 if empty, 0 if not
FFvar$
X=frame number
xFGvar$
Compares lines to
variable level
y,xFGvar$
Compares range to
variable level
FOvar$
Pops variable
FTvar$
X=variable type
xFTvar$
FUvar$
Pushes variable
xFUvar$
Gvar$
P = P + size
Mvar$
Invokes macro
Qvar$
X = var
xUvar$
Unloads x into
variable level
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-119
#D E LT A B uilt-In F u nctio n
Description
Effect On Buffer
y,xUvar$
Unloads x into
variable level
X=y
xXvar$
Extracts lines to
variable level
Lines from P to x
EOLs put into
variable level
y,xXvar$
Extracts chars to
variable level
Characters from y to
x put into variable
level
^\
Caution. If you used the /COMMANDS/ option when you invoked #DELTA, do not push, pop,
or in any other way modify the variable level from which #DELTA is receiving its commands;
doing so can cause #DELTA, and possibly TACL, to fail.
Description
Effect on Buffer
Effect on X, Y, and
Pointer (P)
EIfile$ *
EOfile$ *
xP
Writes lines
Lines from P to x
EOLs sent to output
file
y,xP
Writes chars
xY
Reads lines
P = P + size
* You can modify EI and EO commands with the @ flag to change the delimiter; for example: @EI/$trmnl/
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-120
#D E LT A B uilt-In F u nctio n
command execution. Table 9-9 summarizes the syntax and effects of these
commands.
Table 9-9. #DELTA Control Commands
Command
Description
Effect on Buffer
Exits iteration
Specifies condition
:?
Specifies NOT
condition
Ends condition
Moves X into Y
Y=X; X cleared
Clears X, Y - X and Y
segments and
retrieves buffer
position
X=P
Displays X or Y,X
<
Begins iteration
x<
Iterates x times
>
Ends iteration
The following subsections provide full descriptions of all the #DELTA commands, in
alphabetic sequence.
The A Command
The A command loads the X register with a number that corresponds to the position of
a character in the ASCII character set. The X register value (before execution)
specifies the buffer position, relative to the pointer, of the character to be examined; 0A
refers to the character before the pointer, 1A (or A) to the character after the pointer.
The A command does not change the pointer position. For example:
57> #DELTA
#DELTA 58>
#DELTA 58>
ARGH(.)!
#DELTA 59>
#DELTA 59>
72
#DELTA 60>
#DELTA 60>
33
ARGH!
4JV
EOF!
0A=
EOF!
1A=
EOF!
H is character number 72 in the ASCII set; exclamation point is character number 33.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-121
#D E LT A B uilt-In F u nctio n
If the position specified by the X register is outside the text in the buffer, an error
occurs. However, if you have placed a value in the Y register, #DELTA avoids the error
and loads the Y register value into the X register instead.
The B Command
The B command loads the value 0 into the X register, thus indicating the beginning of
the buffer.
The C Command
The C command moves the pointer the number of positions specified by the contents
of the X register; you can precede the C command with an X register value. The sign of
the number indicates the direction to move: forward (positive) or backward (negative).
You must use a minus sign to indicate a negative number, but positive values are
implied by the absence of a minus sign. If there is no value in the X register, 1 is
assumed.
If you use the : flag before the C command, the command returns -1 if it succeeds, or 0
if the command would try to move the pointer outside the text in the buffer. If the
command is successful, the pointer is moved the specified number of characters; if the
command fails, the pointer is not moved.
For example:
#DELTA 28> v
#DELTA 28> EOF!
This is a test string(.)
#DELTA 29> -2:c = v
#DELTA 29> EOF!
-1
This is a test stri(.)ng
#DELTA 30> 4:c=v
#DELTA 30> EOF!
0
This is a test stri(.)ng
#DELTA 31>
The D Command
The D command moves the pointer a number of characters specified by the contents
of the X register, deleting those characters in the process; you can precede the D
command with an X register value. A minus sign preceding the number specifies that
characters are to be deleted in a backward direction. You must not use a plus sign to
specify forward direction, however; a positive value is implied by the absence of a
minus sign. If there is no value in the X register, 1 is assumed. For example:
65> #DELTA
#DELTA 66>
#DELTA 66>
a(.)rgh!
#DELTA 67>
argh!
1jv
EOF!
dht
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-122
#D E LT A B uilt-In F u nctio n
The EI Command
The EI command opens a file for input. To read a file, you must open the file and
specify that the file is open for input. You cannot open the same file for both input and
output, and you can have only one file open for input and one file open for output at the
same time. If you try to open a nonexistent file for input, an error occurs.
If you follow the EI command with a file name, TACL closes the file currently open for
input and opens the named file. If you omit the file name, TACL closes the file currently
open for input. If you leave a file open when you exit from #DELTA, TACL closes it
automatically.
If you specify a file name with EI, you must end the file name with a dollar sign. If the
file name contains a dollar sign, you must use the @ flag with the command to specify
another delimiter. The delimiter is the first character that follows the command. For
example, the command @EI/$KYRIE.LEE.TESTSRC/ uses slashes (/) as its
delimiters.
This example shows how you can use EI to open a file whose name is supplied as an
argument:
#PUSH fn opfl
#SET fn %1%
== Save file name in fn
#SET /TYPE DELTA/ opfl @EI/[fn]/ == Build custom EI command
[#DEF delcomm DELTA |BODY|
== Define DELTA commands
...
Mopfl$
== Invoke custom EI command
...
]
#DELTA /COMMANDS delcomm/
== Invoke DELTA commands
The EO Command
The EO command opens a file for output. To write to a file, you must open the file and
specify that the file is open for output. You cannot open the same file for both input and
output, and you can have only one file open for input and one file open for output at the
same time. If a file opened for output does not exist, TACL creates an edit file with that
name; if the file does exist, #DELTA appends the lines it writes to the end of the file.
If you follow the EO command with a file name, TACL closes the file currently open for
output and opens the named file. If you omit the file name, #DELTA closes the file
currently open for output. If you leave a file open when you exit from #DELTA, TACL
closes it automatically.
If you specify a file name with EO, you must end the file name with a dollar sign. If the
file name contains a dollar sign, you must use the @ flag with the command to specify
another delimiter. The delimiter is the first character that follows the command. For
example, the command @EO$FURD.UFFDA.TESTSRC uses apostrophes () as its
delimiters.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-123
#D E LT A B uilt-In F u nctio n
The FC Command
The FC command changes the case of text within a specified range. You can specify
the range of text either with an X register value (X lines of text, starting at the current
pointer position), or with X and Y register values (from character Y to character X). If
you use the @ flag with the FC command, the text in the range is changed to
uppercase; if you do not use the @ flag, the text is changed to lowercase.
If FC appears at the beginning of an interactive command line, it is the standard FC
(Fix Command) command.
The FE Command
The FE examines a variable level to see if it is empty. If the variable level contains
nothing, FE loads -1 into the X register; if the variable level contains anything, FE loads
0 into the X register. FE considers a variable level to be empty only if it does not
contain anything, even a space or an end-of-line.
The FF Command
The FF command loads the X register with the frame number associated with a
specified variable level. The FF command must be followed by a variable level name.
The variable level name must be terminated by a dollar sign.
The FG Command
The FG command compares a variable level with a specified range of text. You can
specify the range of text either with an X register value or with X and Y register values.
The comparison is not case-sensitive. If the comparison succeeds, FG loads -1 into the
X register; if the comparison fails, it loads 0 into the X register.
The comparison succeeds only if all characters in the variable level agree with the
buffer text. In this example, the comparison fails because DIGITS contains 10
characters (the 8 digits assigned plus a two-byte end-of-line character) and only 9
characters in the buffer are compared with it:
70> #PUSH digits
71> #SET digits 12345678
72> #DELTA
#DELTA 73> Gdigits$ BJ .,.+8FGdigits$ =
#DELTA 73> EOF!
0,0
If you had used this command instead:
#DELTA 73> Gdigits$ BJ HFGdigits$
the comparison would have succeeded because the entire contents of DIGITS were in
the buffer (the end-of-line character is represented by a null character).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-124
#D E LT A B uilt-In F u nctio n
The FL Command
The FL command loads the X register with the length of the string last inserted by I or
found by S. This is especially useful for doing text replacement where you do not want
to (or cannot) count the length of the search string. For example, you might use the
following in a TACL macro because the length of the first argument of the macro varies
from call to call:
#SET /TYPE DELTA/ cmds ... J <@:S/%1%/; -FL D> ...
#DELTA / COMMANDS cmds /
The iteration searches the buffer for a string that matches an argument of unknown
length; if it finds the string, it sets the X register to the negative (-FL) value of the string
length and deletes that many characters from the buffer. FL is set to zero whenever
#DELTA prompts.
The FO Command
The FO command pops a TACL variable. If you pop the last level of a variable, that
variable is destroyed.
The FT Command
You use the FT command to get or set the type of a variable level. FT must be followed
by the name of a variable level. If the X register is clear, FT returns a value
representing the variable type in the X register.
The values and their types are:
Value
Typ
MACRO
ROUTINE
TEXT
DELTA
ALIAS
DIRECTORY
STRUCT
If the X register contains a value between 1 and 6, FT sets the specified variable level
to the type represented by the value.
The FU Command
The FU command pushes a TACL variable. If you push a variable that does not exist,
#DELTA creates it. If there is a value in the X register when you use the push
command, the new level of the variable contains that value.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-125
#D E LT A B uilt-In F u nctio n
The G Command
The G command copies text from a variable level and inserts it in the buffer, moving
the pointer to the right of the text. The G command must be followed by a variable level
name; that name must be terminated by a dollar sign.
If you precede the G command with the : flag, #DELTA extracts (and deletes) the first
line from the variable level and puts it in the buffer. Without the : flag, #DELTA copies
the entire variable level into the buffer and the variable level remains unchanged.
The X command is the complementary function of the G command.
The H Command
The H command is equivalent to using the commands B,Z; that is, it loads the Y
register with the beginning of the buffer and the X register with the size of the buffer.
You can use the H command in conjunction with other commands to perform an
operation on the whole buffer. For example, the command HT displays the entire
buffer.
The I Command
The I command inserts text into the buffer at the current position. There are three
different ways to use the I command:
test
j iA $
1j v
EOF!
32i v !32 is ASCII code for space
EOF!
5,33i v !33 is ASCII code for exclamation point
EOF!
test
Only when there is no value in either X or Y register can you follow the I command with
text; in the other two cases, the I command must not be followed by text. If the text
string contains a dollar sign, you can use the @ flag with the I command to specify new
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-126
#D E LT A B uilt-In F u nctio n
delimiters around the string; the character immediately to the right of the I command is
the new delimiter. The delimiter is changed only for the current I command.
For example:
#DELTA 45> @I/new$/ v
#DELTA 45> EOF!
a !!!!!new$(.) test
#DELTA 46> I string$ v
#DELTA 46> EOF!
a !!!!!new$ string(.) test
#DELTA 47>
#DELTA uses the ASCII code 0 to mean end-of-line; thus, 0I (or I) breaks a line.
The J Command
The J command moves the pointer to an absolute location specified by the contents of
the X register. Thus, 0J jumps to the beginning of the buffer; 23J jumps to the 23rd
character in the buffer. The J command accepts an X register value; if none is
specified, 0 is assumed.
The K Command
Use the K command to delete a specified range of text, in lines or characters. The
range of text can be specified either with an X register value or with X and Y register
values.
If you specify only an X register value, K deletes x lines starting at the current position.
(If x is negative, K deletes x lines preceding the current position.) The K command with
no range is equivalent to 1K; -K is equivalent to -1K.
If you specify both an X register value and a Y register value, K deletes a range of
characters from position y to position x.
The difference between the K and D commands is that K deletes lines or any range of
characters; D deletes only characters, starting at the current position.
The L Command
The L command moves the pointer the number of lines specified by the contents of the
X register. That value indicates the number of end-of-line characters to skip in search
of a new line. The command 0L moves to the beginning of the current line; 1L moves
to the beginning of the next line. The L command accepts an X register value; if none
is specified, 1 is assumed; -L is equivalent to -1L.
The M Command
The M command executes a #DELTA macro. The M command must be followed by a
variable level name, which must be type DELTA. The name must be terminated by a
dollar sign. The macro uses the same buffer and current pointer value as the command
stream that invoked it. The commands in the macro are executed until the macro
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-127
#D E LT A B uilt-In F u nctio n
encounters the ^\command or the end of the commands in the variable level. When the
macro exits, the buffer and current pointer value remain where the macro left them.
The only way to pass arguments to #DELTA macros is to load the arguments into
variable levels before calling the macro, then, from within the macro, get the contents
of the variables.
The P Command
The P command writes a range of text to the output file. The range of text can be
specified either with an X register value (X lines of text, starting at the current pointer
position) or with X and Y register values (character Y through character X). You cannot
represent a partial line in a file. If you output a line fragment, that fragment becomes a
new line in the output file.
#DELTA does all file I/O in PLAIN mode.
The Q Command
The Q command moves a value from a numeric variable level into the X register. The
variable level name must be terminated by a dollar sign.
To move a numeric variable level into text, you can either insert the variable level
directly with the G command or move the value into the X register with Q and then
insert the contents of the X register into text with the backslash command (that is,
Qvar$\).
The U command is the complementary function of the Q command.
The S Command
The S command searches the buffer for a specified string, starting at the current
position. The search is not case-sensitive. The contents of the X register specify the
search direction-a positive value means search forward; a negative value, backwardand how many occurrences of the string to search for before stopping. The string to be
sought follows the S command and is normally terminated by a dollar sign. If the
search string contains a dollar sign, you can use the @ flag to specify a different
delimiter; for example:
54> #DELTA This is a $test string
#DELTA 55> bj @s/$test/ v
#DELTA 55> EOF!
This is a $test(.) string
#DELTA 56>
In this example, the string $test contains a dollar sign, so you use the @ flag to
specify a slash (/) as the delimiter. The new delimiter must follow the S command.
Using the @ flag changes the delimiter for only the S command that it modifies.
If the search direction is forward, the pointer is set to the right of the matching string; if
the search is backward, the pointer is set to the left of the match.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-128
#D E LT A B uilt-In F u nctio n
If the search string is not found, #DELTA issues an error message and, if the #DELTA
session is not interactive, #DELTA exits. The pointer does not move. You can use the :
flag to enable your #DELTA code to handle search errors-if the string is found, the X
register is set to -1; if not, it is set to 0.
You can also use S with FL to do text replacement.
The T Command
The T command displays a range of text, the contents of a variable level, or a userspecified string.
The range of text can be specified either with an X register value or with X and Y
register values.
To display the contents of a variable level, use the @ flag with the T command. The T
command must be immediately followed by the variable level name; the variable level
name must be terminated by a dollar sign.
For example:
60> #PUSH TEST
61> #SET TEST Test string in a variable
62> #DELTA
#DELTA 63> @Ttest$
#DELTA 63> EOF!
Test string in a variable
#DELTA 64>
You can use the : flag to direct the T command to display a text string. The text follows
the T command and must be terminated with a dollar sign. If the text contains a dollar
sign, you can use the @ flag to specify the string delimiter. The delimiter is the first
character after the T command. In this example, the first :T command uses the dollar
sign terminator; the second :T command types out a string that contains a dollar sign,
so it uses the @ flag to specify a different terminator:
#DELTA 64> :TParsing string...$
#DELTA 64> EOF!
Parsing string...
#DELTA 65> @:T/Couldn't open $GERT.STEIN.NEWMACS/
#DELTA 65> EOF!
Couldn't open $GERT.STEIN.NEWMACS
#DELTA 66>
The U Command
The U command moves the value in the X register into a numeric variable level,
consisting of one line, the text of which is the ASCII representation of a number. The
variable level name must be terminated by a dollar sign.
The U command stores the value of the X register in the variable level, stores the Y
register value in the X register, and sets the Y register to a null value. A second U
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-129
#D E LT A B uilt-In F u nctio n
command could then save the former Y register value in another variable level. For
example:
123,456 Uxval$ Uyval$
puts 456 into XVAL, 123 into YVAL, and clears the X and Y registers.
The U command is the complementary function of the Q command.
The V Command
The V (view) command is most commonly used as an aid in debugging #DELTA
macros and, in general, finding out where you are in the buffer.
The V command displays lines of text and indicates where the pointer is. The X value
determines the number of lines displayed by the V command. 1V (or V) displays the
line that includes the current position; 2V displays the line that includes the current
position, plus one line in either direction.
The number of lines to display is actually determined by the number of end-of-line
characters encountered in either direction from the current position. Note that end-ofline characters include the ends-of-lines at either end of the current line. If there is no
text in either direction, the V command does not report an error.
If you use the : flag with the V command, #DELTA indicates the beginning (B) or end
(Z) of the buffer, if they are within the range specified with the V command.
The X Command
The X command loads a TACL variable level with a range of text in the buffer. The X
command must be immediately followed by the name of a variable level; the variable
level name must be terminated by a dollar sign.
The range of text can be specified either with an X register value or with X and Y
register values: xX var-name$ loads x number of lines from the buffer into varname; y, xX vvar-name$ loads characters from positions y through x into varname.
If you precede the X command with the : flag, #DELTA appends the text to that already
in the variable level. Without the colon flag, #DELTA replaces any existing text in the
variable level with text from the buffer.
The Y Command
The Y command reads text from the input file into the buffer. The contents of the X
register indicate the number of lines to read. If there is no value in the X register,
#DELTA reads, or tries to read, all the lines in the file into the buffer (remember that the
buffer is less than 30,000 characters long).
When the Y command succeeds in reading text into the buffer, it loads the number of
lines read into the X register. If the Y command reads past the end of file, it closes the
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-130
#D E LT A B uilt-In F u nctio n
file. If you use the Y command on a closed file, it loads the value zero into the X
register.
#DELTA does all file I/O in PLAIN mode.
The Z Command
The Z command loads the X register with the size of the currently used portion of the
buffer (in characters). You can use the Z command as a pointer to the end of the buffer.
For example, the commands Z K delete the characters from the current position to the
end of the buffer.
The $ Command
The dollar sign command clears both the X and Y registers.
You may want to use the dollar sign command before a command that can behave
differently depending on whether there are values in the X or Y registers.
The end-of-line following a line of #DELTA commands also clears the X and Y
registers.
The , Command
The comma command moves the contents of the X register to the Y register and clears
the X register. You can then load a second value into the X register. For example:
#DELTA 73> 8 =
#DELTA 73> EOF!
8
#DELTA 74> 8, =
#DELTA
8,0
#DELTA
#DELTA
8,40
#DELTA
74> EOF!
75> 8,40 =
75> EOF!
76>
If you enter another comma and another new X register value, the first Y register value
is lost.
The . Command
The period command loads the current pointer position into the X register.
The = Command
The equal sign command displays the contents of the X and Y registers on your
current output device. The = command is useful for debugging macros. If you are not
sure what value is in the X and Y registers before a command is executed, insert the
equal sign before that command. (Remember to remove the equal sign when you have
finished debugging; the = command destroys the contents of the X and Y registers.)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-131
#D E LT A B uilt-In F u nctio n
The \ Command
The backslash command converts a value in the X register to a number in text and vice
versa.
If there is no value in the X register and the text to the right of the pointer is a number,
#DELTA converts the text to a numeric value and loads it into the X register. For
example, if the text is 123ABC, the \ command loads 123 into the X register. If the text
is nonnumeric or is empty, an error occurs.
If there is a value in the X register, #DELTA inserts the textual representation of the
value into the buffer at the current position, moving the pointer to the right of the
inserted number.
If there is a value in the Y register, #DELTA inserts the value from the X register (zero,
if there is none) and right-justifies the inserted number in a field y characters wide. If y
is zero or greater, #DELTA fills the field with leading spaces; if y is less than zero,
leading zeros are used instead. If the absolute value of y is less than or equal to the
number of digits in the value to be inserted, #DELTA simply inserts it.
The ^\ Command
This command terminates a #DELTA macro begun by the M command.
Condition to be Tested
Is X equal to zero?
The : flag, placed before the question mark, is the NOT operator. For example, 1?E is
false, but 1:?E is true.
In this example, the character before the pointer is converted into its ASCII value and
is loaded into the X register. The conditional test then tests whether the character is an
alphabetic character. If it is not, #DELTA replaces it with a space (-D I $ deletes the
character and inserts a space):
0A :?A -D I $'
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-132
#D E LT A B uilt-In F u nctio n
@;
:;
@:;
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-133
# D E V IC E IN F O B uilt-In F u nctio n
Result
#DEVICEINFO returns the information requested by the options. If you specify more
than one option, #DEVICEINFO lists the items of information, separated by spaces, in
the same order as the option requests. If you specify a device or file that does not
exist, or if an error occurs, #DEVICEINFO returns the following:
#E M P T Y B uilt-In F u nctio n
Result
#EMPTY returns -1 if text is empty; otherwise, it returns 0.
Considerations
Example
This example from a macro verifies that the nth argument contains text before
processing that argument.
[#IF NOT [#EMPTY % n%] |THEN|
...
code for nonempty nth argument
...
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-135
#E M P T Y V B uilt-In F u nctio n
Result
#EMPTYV returns -1 if the string is empty; otherwise, it returns 0.
Consideration
Use the #EMPTY built-in function to determine if specified text is empty.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-136
# E M S A D D S U B JE C T B uilt-In F u nctio n
Result
#EMSADDSUBJECT returns a numeric status code indicating the outcome of the
EMSADDSUBJECT procedure.
The meaning of the status code:
Code
Condition
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
Code
Condition
-9
-10
Invalid subsystem ID
-11
-12
# E M S A D D S U B JE C T B uilt-In F u nctio n
Considerations
Every event message has at least one subject, which you specify to the #EMSINIT
procedure. Use #EMSADDSUBJECT to specify additional subjects.
#EMSADDSUBJECT inserts two tokens into the buffer: the ZEMS-TKN-SUBJECTMARK token, which always precedes a subject and the subject token you
specified.
If the subsystem that generates the event message needs to include tokens from
another subsystem (often a lower-level subsystem), its call to #SSPUT(V) must
include the SSID option, which specifies the subsystem ID of the other subsystem.
When you specify the SSID option, every token placed in the buffer on that
procedure call is in an extended form that includes the SSID you specified.
To supply token values from a variable level, use the #EMSADDSUBJECTV built-in
function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-138
# E M S A D D S U B JE C T V B uilt-In F u nctio n
Result
#EMSADDSUBJECTV returns a numeric status code indicating the outcome of the
EMSADDSUBJECT procedure.
The meaning of the status code:
Code
Condition
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-139
# E M S A D D S U B JE C T V B uilt-In F u nctio n
Code
Condition
-8
-9
-10
Invalid subsystem ID
-11
-12
Considerations
Every event message has at least one subject, which you specify to the
#EMSINIT(V) procedure. Use #EMSADDSUBJECTV to specify additional subjects.
#EMSADDSUBJECTV inserts two tokens into the buffer: the ZEMS-TKNSUBJECT- MARK token, which always precedes a subject, and the subject token
variable or the STRUCT.
If the subsystem that generates the event message needs to include tokens from
another subsystem (often a lower-level subsystem), its call to #SSPUT(V) must
include the SSID option, which specifies the subsystem ID of the other subsystem.
When you specify the SSID option, every token placed in the buffer on that
procedure call is in an extended form that includes the SSID you specified.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-140
# E M S G E T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-141
# E M S G E T B uilt-In F u nctio n
buffer-var
is the name of the message buffer from which information is to be taken; it must be
a writable STRUCT that has been initialized by #SSINIT.
get-op
is one of these:
token-code
directs #EMSGET to return the token value or values associated with tokencode.
If token-code is a token that marks the beginning of a list, #EMSGET selects
the list so that subsequent calls can retrieve tokens within the list. If tokencode is ZSPI^TKN^ENDLIST, #EMSGET pops out of the list.
token-code can be any of the header tokens listed under Header Tokens
and Special Operation for #SSGET and #SSGETV in the description of the
#SSGET built-in function. You can also supply the token
ZSPI^TKN^DEFAULT^SSID to obtain the default subsystem ID at the current
position.
ZSPI^TKN^COUNT c-token-id
directs #EMSGET to return the number of occurrences of the token specified
by the token code or the token map c-token-id, starting with the occurrence
specified by index. To count all occurrences in the list, specify an index of 1.
If c-token-id is omitted or equal to ZSPI^VAL^NULL^TOKENCODE, and
index is omitted or zero, #EMSGET counts occurrences of the current token,
including the current occurrence of that token.
ZSPI^TKN^LEN l-token-id
directs #EMSGET to return the byte length of the token specified by the token
code or token map l-token-id. This is the size of the buffer needed to
contain the stated occurrence of the token value. For variable-length token
values, this includes the two bytes required for the length word: The byte
length returned is token-value[0]+2.
If this option is omitted or l-token-id is ZSPI^VAL^NULL^TOKENCODE,
and index is omitted or zero, #EMSGET returns the length of the current
occurrence of the current token.
If l-token-id is a token map, this operation returns the length contained in
that map; the value in the buffer can be longer or shorter than this length. To
get the actual length of the token value, call #EMSGET with ZSPI^TKN^LEN
and a token code made up of ZSPI^TYP^STRUCT and the token number from
the token map. This returns the length of the value, including 2 bytes for the
length field. Subtract 2 from this result to get the length of the value itself.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-142
# E M S G E T B uilt-In F u nctio n
ZSPI^TKN^NEXTCODE
directs #EMSGET to return the next token code that is different from the
current token code, followed by the subsystem ID. The subsystem ID returned
in the result always has a version field of zero (null).
The index parameter has no effect on this operation, but if you supply it, it must
be zero.
ZSPI^TKN^NEXTTOKEN
directs #EMSGET to return the next token code, followed by the subsystem ID.
The subsystem ID returned always has a version field of zero (null).
This operation differs from ZSPI^TKN^NEXTCODE in that it always returns the
token code of the next token, whether it is the same as that of the current
token or different, and whether the token is within a list or not. The operation
returns multiple occurrences of the same token code in the same order as they
were added to the buffer with #SSPUT(V).
The index and count parameters have no effect on this operation, but if you
use them, index must be zero; count is always returned as 1.
Note. The special operations ZSPI^TKN^NEXTCODE and ZSPI^TKN^NEXTTOKEN
return only token codes. In particular, note that tokens added to the buffer using
#SSPUTV with a token map are carried in the buffer with a token code of type
ZSPI^TYP^STRUCT. The NEXTCODE and NEXTTOKEN operations return that token
code, not the token map used with #SSPUTV.
ZSPI^TKN^OFFSET o-token-id
directs #EMSGET to return the byte offset of the token specified by the token
code or token map o-token-id. The value returned is the offset from the
start of the buffer to the value associated with the specified token code and
index. (For variable-length values, the token value begins with the length word;
the offset given is the offset to that length word.)
If you omit this option or if o-token-id is equal to
ZSPI^VAL^NULL^TOKENCODE, and index is omitted or zero, #EMSGET
returns the length of the current occurrence of the current token.
You must supply appropriate token code definitions. TACL supports the special
semantics for only those SPI special token codes shown; any other token
codes are assumed to adhere to standard semantics.
Result
#EMSGET returns a numeric status code indicating the outcome of the SSGET
procedure.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-143
# E M S G E T B uilt-In F u nctio n
Description
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
-11
-12
If the status code is 0 (no error), it is followed by a space and a space-separated list of
the relevant EMSGET results in the TACL external representation:
Considerations
Tokens extracted by #EMSGET are not deleted or removed from the buffer.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-144
# E M S G E T B uilt-In F u nctio n
When the current position is within a particular list, all #EMSGET calls pertain only
to tokens within that list (except that header fields are always accessible). You can
exit from the list by calling #EMSGET to get the ZSPI^TKN^ENDLIST token.
When token-code is ZSPI^TKN^ENDLIST, the index and count parameters have
no effect. However, if you supply them, index must be 0 or 1; count is always
returned as 1.
To retrieve token values into a STRUCT, use the #EMSGETV built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-145
# E M S G E T V B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-146
# E M S G E T V B uilt-In F u nctio n
result-var
is the name of the writable STRUCT into which #EMSGETV is to store the data
returned. The original contents of the STRUCT are lost.
If the status code in the function result is zero (no error), the result stored in
result-var is:
Result
#EMSGETV returns a numeric status code indicating the outcome of the SSGET
procedure. The meaning of the status code:
Code
Description
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
-11
-12
# E M S G E T V B uilt-In F u nctio n
If no error occurred, and get-op is token-id, the status code is followed by a space
and the number of token values returned.
Considerations
Tokens extracted by #EMSGETV are not deleted or removed from the buffer.
When the current position is within a list, all #EMSGETV calls pertain only to
tokens within that list (except that header fields are always accessible). You can
exit from the list by calling #EMSGETV to get the ZSPI^TKN^ENDLIST token.
When token-id is ZSPI^TKN^ENDLIST, the index and count parameters have
no effect; however, if you supply them, index must be 0 or 1.
When using #EMSGETV with a token map for the token-id parameter, the map
can specify a structure version that is longer or shorter than the structure contained
in the buffer. If the requested version is longer than the version in the buffer,
#EMSGETV calls SSNULL to set to null values the new fields that are not obtained
from the buffer. If the requested version is shorter than the one in the buffer,
#EMSGETV returns only the requested length.
If the data returned by #EMSGETV is longer than the data area of the STRUCT
identified by result-var, TACL discards the excess bytes without notification. If
the data is shorter than the data area of result-var, TACL sets the entire
STRUCT to its default values, then overwrites the beginning of the data bytes of
the STRUCT with the returned data. No type conversions of any kind are done.
This means that, for instance, if the token retrieved is of type ZSPI^TYP^INT and
the result-var STRUCT consists of a single field of type INT2, the token value
would be in the high-order 16 bits of the INT2 field, not the low-order 16 bits.
If you specified the COUNT option, TACL puts all occurrences of the token value
into the STRUCT exactly as returned by #EMSGETV, subject to the size
constraints mentioned in the previous consideration. If the tokens are variablelength tokens, each token value consists of a length word followed by the actual
value, and the actual value is word-aligned.
To retrieve tokens and convert them to external representation as the result of the
function call, use the #SSGET built-in function.
Header tokens, and one special operation, can be passed in token-id to get
corresponding values. They are described under Header Tokens and Special
Operation for #SSGET and #SSGETV in the explanation of the #SSGET built-in
function.
Example
To extract a subject token, follow two steps:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-148
# E M S G E T V B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-149
# E M S IN IT B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-150
# E M S IN IT B uilt-In F u nctio n
Result
#EMSINIT returns a numeric status code indicating the outcome of the initialization.
The meaning of the code:
Code
Description
No error
-2
-3
Missing parameter
-4
-5
Buffer full
-7
Internal error
-10
Invalid subsystem ID
-12
-30
Considerations
You can omit the token-value parameter if the token length specified by token ID is
zero. Otherwise, the token-value parameter is required.
To initialize a buffer and supply event information from a variable, use the
#EMSINITV built-in function.
Buffer length larger than ZEMS-VAL-EVT-BUFLEN indicates that the length of the
STRUCT passed as the buffer-var parameter to the #EMSINIT built in exceeds
ZEMS-VAL-EVT-BUFLEN (whose current value is 4024 bytes).
Example
Here is an example of an #EMSINIT call, using the TMF subsystem:
#PUSH ems^err event^num
[#DEF buf STRUCT
BEGIN
INT length;
CHAR text (0:255);
END;
]
#SET event^num 1
#SET ems^err &
[#EMSINIT /SSID/ ZTMF^VAL^SSID TIMESTAMP &
[#JULIANTIMESTAMP 2] &
buf [ZTMF^VAL^SSID] [event^num] ZEMS^CMD^CONTROL]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-151
#E M S IN IT V B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-152
#E M S IN IT V B uilt-In F u nctio n
Result
#EMSINITV returns a numeric status code indicating the outcome of the initialization.
The meaning of the code:
Code
Description
No error
-2
-3
Missing parameter
-4
-5
Buffer full
-7
Internal error
-10
Invalid subsystem ID
-12
Considerations
If the data in source-var is longer than the data area expected by #EMSINITV,
the excess bytes are ignored without any notification. If the data in source-var is
shorter than the data area expected, #EMSINITV sets the remainder of the token
value to unspecified values.
To initialize a buffer and supply event information in external form, use the
#EMSINIT built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-153
#E M S T E X T B uilt-In F u nctio n
Result
#EMSTEXT returns the formatted text from the event buffer.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-154
#E M S T E X T B uilt-In F u nctio n
Considerations
You cannot access the lengths result from the EMSTEXT procedure with
#EMSTEXT; you must use #EMSTEXTV instead.
The INT(32) result of EMSTEXT is not included in the result of #EMSTEXT; you
must use #EMSTEXTV to access it.
Because #EMSTEXT can produce more than one line, you should always use
square brackets around the construct containing the invocation of #EMSTEXT:
[#OUTPUT [#EMSTEXT var]] and [#SET var2 [#EMSTEXT var1]]
are correct, whereas
#OUTPUT [#EMSTEXT var] and #SET var2 [#EMSTEXT var1]
would produce TACL errors if #EMSTEXT returned more than a single line.
#EMSTEXT does not suppress leading and trailing blank lines in the result, but
remember that TACL ignores leading and trailing white space on arguments in
most cases.
#EMSTEXT does not suppress leading and trailing spaces on nonblank lines in the
result, but remember that TACL ignores leading and trailing white space on
arguments in most cases.
If a STRUCT is longer than the data it is to contain, the unused bytes are ignored
on input and unchanged on output.
If a STRUCT is too short, an error results.
To obtain information from an event buffer and place the printable text into a
STRUCT, use the #EMSTEXTV built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-155
#E M S T E X T V B uilt-In F u nctio n
Result
#EMSTEXTV returns a space-separated pair of signed integers representing the result
of EMSTEXT. Their meaning is:
Result
Description
00
No error
0 22
0 29
Missing parameter
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-156
#E M S T E X T V B uilt-In F u nctio n
Result
Description
1 code
2 +code
2 -code
3 code
40
60
Malformed template
7 code
Considerations
If a STRUCT is longer than the data it is to contain, the unused bytes are ignored
on input and unchanged on output.
If a STRUCT is too short, an error results.
To obtain information from an event buffer and obtain the printable text as the
function result, use the #EMSTEXT built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-157
# E N D T R A N S A C T IO N B uilt-In F u nctio n
Result
#ENDTRANSACTION returns 0, if successful, or a file-system error indicating the
reason ENDTRANSACTION failed.
Consideration
To abort and back out a transaction, use the #ABORTTRANSACTION built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-158
# E O F B uilt-In F u nctio n
Result
#EOF returns nothing.
Consideration
Different processes handle end-of-file differently. For example, an EDIT process
started by the command
EDIT /INV in_var DYNAMIC/
stops as soon as it reads an end-of-file produced by
#EOF in_var
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-159
# E R R O R N U M B E R S B u ilt-In V a ria b le
Result
#ERRORNUMBERS returns a space-separated list of four integer numbers that
describe the most recent error. If the first number in the list is less than 1024, it is the
number of a file-system error or sequential I/O error. If the number is 1024 or larger, it
is a TACL error number. The other three numbers are used in certain cases to provide
additional information:
Considerations
For more information about error messages, see the Guardian Procedure Calls
Reference Manual and the Guardian Procedure Errors and Messages Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-160
# E R R O R N U M B E R S B u ilt-In V a ria b le
Example
If you try to create a process that already exists, you receive this error when you output
the error numbers:
37> #OUTPUT [#ERRORNUMBERS]
1149 1 48 0
The first number is a TACL #NEWPROCESS error (1149). The second number is a
PROCESS_CREATE_ error number (1), which usually indicates that a file system error
occurred. The third number is a file-system error number (48), which indicates that a
security violation occurred. The fourth number is not used.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-161
# E R R O R T E X T B uilt-In F u nctio n
Result
#ERRORTEXT returns nothing.
Considerations
If an error occurs while you are filtering _ERROR (see #EXCEPTION Built-In
Function on page 9-163), TACL stores the resulting error text internally. Previously
stored text is lost, so only the most recent error text is available.
The captured error text is not fully formatted and usually contains some internal
representations. It is, therefore, suitable only for output with #OUTPUTV or
OUTVAR.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-162
# E X C E P T IO N B uilt-In F u nctio n
Result
#EXCEPTION returns _CALL, if the routine issuing #EXCEPTION was invoked
normally, or returns the name of the exception if the routine was invoked in response to
an exception that it had filtered. (See the TACL Programming Guide for a discussion of
exception handling.)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-163
# E X IT B u ilt-In V a ria b le
Result
#EXIT returns 0 if the EXIT flag is off and -1 if it is on. If the EXIT flag is on, it causes
TACL to exit as soon as its buffer becomes empty.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-164
# E X T R A C T B uilt-In F u nctio n
Result
#EXTRACT returns the first line of the specified variable level and deletes the line from
the variable level.
Example
21> #PUSH fline
22> #SET fline [#EXTRACT linevar]
Consideration
To move the first line of a variable level to another variable level, use the #EXTRACTV
built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-165
# E X T R A C T V B uilt-In F u nctio n
Result
#EXTRACTV returns nothing.
Considerations
The construct
#EXTRACTV var struct
is not equivalent to
#SET struct [#EXTRACT var]
The former construct is faster and is not subject to errors resulting from type checking.
If the data supplied exceeds the data area of the specified STRUCT, TACL
discards the excess bytes without any notification.
If the data supplied is shorter than the data area of the STRUCT, TACL sets the
entire STRUCT to default values and then moves the data into the beginning of the
data bytes of the STRUCT.
To retrieve the first line of a variable level as the function result, use the
#EXTRACT built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-166
#F IL E G E T LO C K IN F O B uilt-In F u nctio n
#F IL E G E T LO C K IN F O B uilt-In F u nctio n
== 0 = file, 1 = record
== <0> set if generic lock
== <1:15> are reserved
INT n^participants; == number of holders/waiters
== for lock
INT2 record^id;
== if record lock and not
== key-sequenced
INT key^length;
== for key-sequenced record
== locks; 0 if not
== key-sequenced
CHAR key(0:255);
== key for key-sequenced
END;
]
== record locks
participants
is a STRUCT that is to receive information about processes or transactions
that hold or wait for the lock; it must be defined as follows:
[#DEF participants STRUCT
BEGIN
STRUCT locker(0:mp-1); ==
BEGIN
UINT flags;
==
==
==
==
==
==
==
FILLER 2;
==
PHANDLE process;
==
==
TRANSID transid
==
REDEFINES process; ==
END;
END;
]
mp = max participants
<0> set for process
clear for
transaction
<1:3> 0=waiting,
1=granted
<4> internal use
<5:15> reserved
reserved
process holding or
waiting for the lock
transaction holding or
waiting for the lock
Result
The #FILEGETLOCKINFO built-in function returns a number that indicates the status
of the operation.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-168
#F IL E G E T LO C K IN F O B uilt-In F u nctio n
Meaning
Success
-1
-2
-3
The participants STRUCT is of the wrong size. (This STRUCT can vary in
size, but it must always be a multiple of the size that would be required for
one participant.)
45
The participants STRUCT was too small to hold all the lock holders and
waiters for the locked resource in the lock description STRUCT. The call
was successful, but only the number of participants specified by max
participants were returned.
Success
-1
-2
-3
The participants STRUCT is the wrong size. (This STRUCT can vary in
size, but it must always be a multiple of the size that would be required for
one participant.)
If #FILEGETLOCKINFO is called to find locks on a disk volume and the status code is
0 (no error) or 45 (warning; there were more lock holders or waiters than would fit into
the participants structure), the status number is followed by a space and the name of
the locked file. The file name is in the form subvolume.file, without a node name or
volume name.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-169
CODE
returns the numeric file code (0, if the file does not exist); see the FUP INFO
command in the File Utility Program (FUP) Reference Manual. This output
includes file type 800, the native object file for TNS/E systems.
CORRUPT
returns -1 if the file exists and has been corrupted; otherwise, it returns 0. (If a
FUP DUP operation is writing to the file, it is considered to be corrupt until the
operation is finished.)
CRASHOPEN
returns -1 if the file is marked crash-open, meaning the file was not closed
normally by the disk process; otherwise, it returns 0.
CREATION_GMT
returns the time and date when the file was created, expressed as a four-word
timestamp (0, if the file does not exist or if it was created prior to the B40 RVU).
DATACOMPRESSION
returns -1 if the file exists, is key-sequenced, and uses data compression;
otherwise, it returns 0.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-170
DEVICETYPE
returns the numeric device type word (0, if the file does not exist); see the
Guardian Procedure Calls Reference Manual.
EOF
returns the numeric value of the end-of-file pointer, which represents the size of
the file in bytes (0, if the file does not exist).
EXISTENCE
returns -1 if the file exists; if not, it returns 0.
EXTENTSALLOCATED
returns the number of file extents currently allocated (0, if the file does not
exist).
FILE
returns the file-name portion of the fully expanded file name (missing fields in
file-name are supplied by the current defaults); the file need not exist. If the file
is a temporary file, FILE returns nothing.
FILEFORMAT
returns one of these:
1
FILESTRUCTURE
returns a numeric value that indicates the structure of the file:
0
Relative
Entry-sequenced
Key-sequenced
FULLNAME
returns the fully expanded file name (missing fields in file-name are supplied by
the current defaults). The define name is returned if a define name is specified.
The file need not exist.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-171
INCOMPLETESQLDDL
returns -1 if the file exists and an SQL DDL operation is currently in progress.
Otherwise, it returns 0.
INDEXCOMPRESSION
returns -1 if the file exists, is key-sequenced, and uses index compression;
otherwise, it returns 0.
LASTOPEN_GMT
returns the time and date when the file was last opened, expressed as a fourword timestamp. (If the file does not exist, or has not been opened since before
the B20 software RVU, this option returns 0.)
LICENSED
returns -1 if the file exists and is licensed; otherwise, it returns 0.
MAXBYTES
returns the maximum number of bytes configured for the file (0, if the file does
not exist).
MAXEXTENTS
returns the maximum number of file extents configured for the file (0, if the file
does not exist).
MODIFICATION
returns the numeric modification date (a three-word timestamp); if the file does
not exist, this option returns 0.
When a file is copied from one system to another system in a different time
zone without modifying the source date of the file, the MODIFICATION option
returns the file modification time as the local civil time of the system from which
the file was copied.
MODIFICATION_LCT
returns the time and date when the file was last modified, expressed as a fourword timestamp. The time is expressed in the local civil time (LCT) of the
system on which the file resides. If the file does not exist, returns 0.
When a file is copied from one system to another system in a different time
zone without modifying the source date of the file, the MODIFICATION_LCT
option returns a timestamp that shows the file modification time as the local
civil time of the system to which the file was copied.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-172
ODDUNSTR
returns -1 if the file exists, is unstructured, and was created with the
ODDUNSTR parameter in effect; otherwise, it returns 0.
OPENNOW
returns -1 if the file exists and is currently open; otherwise, it returns 0.
OWNER
returns the owners user ID (0,0 if the file does not exist).
PHYSICALFILENAME
returns the physical file name that is associated with the physical file where the
data resides if the specified file is a logical file. If the file is a remote file, the
remote system name is also returned. If the file does not exist, nothing is
returned.
PHYSICALVOLUME
returns the physical volume name that is associated with the physical file
where the data resides if the specified file is a logical file. If the file is a remote
file, the remote system name is also returned. If no physical volume name has
been specified, the physical volume is chosen by the system and this name is
returned. If the file does not exist, nothing is returned.
PRIMARY
returns the primary extent size (0, if the file does not exist).
PROGID
returns -1 if the file exists and has PROGID authority; otherwise, it returns 0.
RECORDLENGTH
returns the logical record length for the file (0, if the file does not exist or is
unstructured).
REFRESH
returns -1 if the file exists and its refresh flag is set; otherwise, it returns 0.
SECONDARY
returns the secondary extent size (0, if the file does not exist).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-173
SECURITY
returns the security established for the file:
rwep
****
####
*SQL
blank
SUBVOL
returns the subvolume-name portion of the file name (missing fields in filename are supplied by the current defaults); the file need not exist. If the file is a
temporary file, SUBVOL returns the file-name portion (#nnnn).
SYSTEM
returns the node-name portion of the file name (missing fields in file-name are
supplied by the current defaults); the file need not exist. If neither the defaults
nor file-name includes a node name, SYSTEM returns nothing.
UNRECLAIMEDFREESPACE
returns -1 if the file exists and an SQL DDL operation has left unreclaimed free
space. Otherwise, it returns 0.
VOLUME
returns the volume-name portion of the file name, using the current defaults if
not specified in the file name. The define name is returned if a define name is
specified. The file need not exist.
file-name
is the name of the file. More than one file can be specified. When specifying a file
name, TACL requires a subvolume name if you supply a volume name. To obtain
the volume portion of the current defaults, use this command:
#FILEINFO /VOLUME/ [#DEFAULTS].X
The file X does not need to exist.
Result
#FILEINFO returns the information requested.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-174
Considerations
If you specify more than one request option, the items of information are listed,
separated by spaces, in the same order as the requests.
Because FILE and SYSTEM can return nothing, you should specify them last in
the list of options to avoid confusion. When assigning results with #SETMANY, for
example, you avoid loss of synchronization between the items returned and the
variable levels that receive them.
If the RVU of the system (system procedure
FILE_GETINFOLISTBYNAME_) does not support INCOMPLETESQLDDL,
UNRECLAIMEDFREESPACE, PHYSICALVOLUME, or PHYSICALFILENAME, this
message is generated:
*ERROR* FILE_GETINFOLISTBYNAME_ error = 561
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-175
# F IL E N A M E S B uilt-In F u nctio n
Result
#FILENAMES returns a space-separated list of file names.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-176
# F IL E N A M E S B uilt-In F u nctio n
Consideration
File names within a volume are returned in alphabetical order, but volumes are
processed in logical-device number order.
Examples
This example illustrates the output of the #FILENAMES built-in function:
17> #OUTPUT [#FILENAMES $BOOKS.TACL.SEC*]
$BOOKS.TACL.SEC01 $BOOKS.TACL.SEC02 $BOOKS.TACL.SEC03
18>
The asterisk in the file-name template instructs #FILENAMES to display the names of
all files that begin with SEC, regardless of which, or how many, characters follow. This
example illustrates the use of two file-name template characters. The asterisk (*) in the
subvolume indicates that you want TACL to search for any subvolume that begins with
BOOK. The question mark (?) in the file name indicates that you want to list the name
of any file whose name has SECT in the first four positions, any character in the fifth
position, and a 2 in the sixth position:
18> #OUTPUT [#FILENAMES book*.sect?2]
BOOK1.SECT02 BOOK2.SECT12
19>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-177
#F IL T E R B uilt-In F u nctio n
Result
#FILTER returns nothing.
Considerations
A portion of a TACL program that performs the actions required by one or more
exceptions is known as an exception handler. An exception handler must do the
following, within a routine:
Include a #CASE built-in function call to handle each of the exceptions the
handler supports. The #EXCEPTION built-in function returns the type of
exception that invoked the handler; use it to direct the #CASE function.
Specify names of exceptions supported by the handler. For this step, use the
#FILTER built-in function to specify the exceptions. TACL does not invoke an
exception handler for an exception unless it is listed in the #FILTER list.
If your code contains these two items and an exception occurs while one of your
functions is executing, the TACL process will invoke the #EXCEPTION built-in function
with the name of the exception that occurred.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-178
#F IL T E R B uilt-In F u nctio n
Only the most recent #FILTER in a routine has any effect. If a routine that contains
a filter list calls another routine that also contains a filter list, the list in the called
routine becomes active. When control is returned from that routine, the filter list in
the calling routine resumes active status. If a routine contains more than one
#FILTER function call, the latest list supersedes all previous lists.
When an exception occurs, if the current routine has no exception handler, TACL
automatically exits that routine and pops you out of routines until it finds a #FILTER
for that exception and reinvokes the routine containing the #FILTER. If TACL finds
no such routine, it performs its normal exception handling: it resets frames and
results and, if the exception is the predefined _ERROR exception, it displays an
error message.
To determine why an exception handler was invoked, use the #EXCEPTION builtin function. To raise an exception, use the #RAISE built-in function.
Example
This example shows a #FILTER call that lists two exceptions:
#FILTER _ERROR userex
For examples showing the use of #FILTER with exception handlers, refer to the TACL
Programming Guide.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-179
#F R A M E B uilt-In F u nctio n
Result
#FRAME returns nothing.
Considerations
All variables pushed after a #FRAME are automatically popped when a matching
#UNFRAME is executed. This allows you to control local variables without having
to explicitly pop them.
Nesting of frames is allowed.
Use #VARIABLEINFO with the / FRAME / option to determine the frame level of a
particular variable.
#FRAME does not restrict the variable levels you can access. You can always refer
to all existing variable levels regardless of your frame.
If an error occurs in a macro or routine, TACL restores the frame level of all
variables to the level in effect when the macro or routine was invoked.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-180
#G E T C O N F IG U R A T IO N B uilt-In F u nctio n
CMONTIMEOUT
specifies the number of seconds that TACL is to wait for any $CMON
operation. This option is initially set to 30.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-181
#G E T C O N F IG U R A T IO N B uilt-In F u nctio n
CONFIGRUN
if PROCESSLAUNCH, then the TACL RUN[D] command was configured to call
the system procedure PROCESS_LAUNCH_ to start the process. In this case,
the additional RUN[D] command options, MAXMAINSTACKSIZE,
MAXNATIVEHEAPSIZE, and GUARANTEEDSWAPSPACE, are available.
if PROCESSCREATE, then the TACL RUN[D] command was configured to call
the system procedure PROCESS_CREATE_ to start the process. In this case,
thee additional RUN[D] command options, MAXMAINSTACKSIZE,
MAXNATIVEHEAPSIZE, and GUARANTEEDSWAPSPACE, are not available.
LOGOFFSCREENCLEAR
if not zero, specifies that if TACL is interactive, and the IN file is a 65xx
terminal, the terminal memory is cleared at (#)LOGOFF unless the NOCLEAR
option is supplied. The CLEAR and NOCLEAR options always override the
automatic operation. This option is initially set to -1.
NAMELOGON
if not zero, specifies that the LOGON command, in both the logged-off and
logged-on states, and #CHANGEUSER do not accept user numbers but
require that user names be used. This option is initially set to 0.
NOCHANGEUSER
if not zero, TACL disables the ability to log on from a logged-on state. This
option is initially set to 0.
REMOTECMONREQUIRED
if not zero, specifies that all operations requiring approval by a remote $CMON
are denied if that remote $CMON is unavailable or is running too slowly.
$CMON approval is not needed if the TACL is already logged on as the super
ID. This option is initially set to 0.
REMOTECMONTIMEOUT
specifies the number of seconds that TACL is to wait for any $CMON operation
involving a remote $CMON. This option is initially set to 30.
REMOTESUPERID
if zero, specifies that if TACL is started remotely, any attempt to log on (or use
#CHANGEUSER) with the super ID (255,255) results in an illegal logon. This
option is initially set to -1 (disabled).
REQUESTCMONUSERCONFIG
if not zero, after a LOGON command or #CHANGEUSER built-in function is
executed, the TACL process sends a message to the $CMON process
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-182
#G E T C O N F IG U R A T IO N B uilt-In F u nctio n
requesting the configuration parameters (the flag settings) in effect for the
current user.
This option is meaningful only if the $CMON process has been coded to return
the appropriate information. Otherwise the request is ignored. Use of this
option allows $CMON to control (and change) the flag settings for each logon
session. These flag settings are then returned to the TACL process.
This option is initially set to 0.
Regardless of the setting, when a LOGOFF command has been executed and
followed (at some point) by a LOGON command or when a noninteractive
TACL process is started, the TACL process requests the configuration
information from the $CMON process.
STOPONFEMODEMERR
if not zero, specifies that the TACL process stops when error 140
(FEMODEMERR) is encountered on its input. If the TACL process is started
with the PORTTACL startup parameter, then this TACL configuration setting is
ignored (TACL goes to the logged off state and waits for a modem connect
when error 140 is encountered).
The option is initially set to 0, meaning the TACL process is put in a logged off
state and waits for a modem connection when an error 140 is encountered.
Result
#GETCONFIGURATION returns a space-separated list of the selected values in the
order of their request.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-183
#G E T P R O C E S S S T A T E B uilt-In F u nctio n
#G E T P R O C E S S S T A T E B uilt-In F u nctio n
Results
The #GETPROCESSSTATE built-in function returns a space-separated list of the
selected values, in the order of their request.
If you do not specify any options, #GETPROCESSSTATE returns a space-separated
list with a one or zero for each process state option, specified from left to right as
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-185
#G E T P R O C E S S S T A T E B uilt-In F u nctio n
Considerations
The term TSN-TACL refers to a TACL process that Safeguard software starts after
authenticating the user of the TACL process.
The TSNLOGON flag is set as follows for descendent TACL processes:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-186
# G E T S C A N B uilt-In F u nctio n
Result
#GETSCAN returns the number of characters that #ARGUMENT has passed over, not
including the routine name and the first character after the name.
Consideration
To determine whether there are more arguments in an argument set, use the #MORE
built-in function. To specify a starting position at which the next #ARGUMENT function
is to resume processing arguments, use the #SETSCAN built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-187
# H E L P K E Y B u ilt-In V a ria b le
Result
#HELPKEY returns the name of the current help key or, if there is no help key, returns
nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-188
# H IG H P IN B u ilt-In V a ria b le
Considerations
The default value for #HIGHPIN depends on the forced-low attribute of the TACL
process. To ensure a default value for #HIGHPIN, set it to the desired value in the
TACLLOCL or TACLCSTM file.
The #HIGHPIN built-in variable can be pushed, popped, and expanded like any
other built-in variable.
The HIGHPIN option on a RUN command overrides the value of the #HIGHPIN
variable for the new process. TACL uses the #HIGHPIN setting when there is no
HIGHPIN directive on a RUN command or #NEWPROCESS call.
Use #PUSH #HIGHPIN (or PUSH #HIGHPIN) to save the current #HIGHPIN
setting.
Use #POP #HIGHPIN (or POP #HIGHPIN) to restore #HIGHPIN to its previous
identity, the last copy pushed.
Use #SET #HIGHPIN (or SET VARIABLE #HIGHPIN) to specify the default PIN
range.
OFF
specifies that processes run at a low PIN regardless of any other
considerations.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-189
# H IS T O R Y B uilt-In F u nctio n
Result
#HISTORY with the CLEARLAST or RESET options returns nothing. #HISTORY with
the SHOW option returns the last num commands. #HISTORY with no options returns
all previous command lines that are still in the history buffer.
Considerations
The history buffer is 1000 characters long; it contains zero or more lines. Each line
stored in the history buffer requires as many bytes as the line contains, plus one
extra byte.
#HISTORY within a TACL macro or routine shows the lines in the history buffer
that lead to the invocation. The result does not include the lines in the macro itself.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-190
#H O M E B u ilt-In V a ria b le
Result
#HOME returns the full path-name of the home directory.
Considerations
When you first log on, #HOME is initialized to : (the root directory).
Use #PUSH #HOME (or PUSH #HOME) to save a copy of the name of your home
directory.
Use #POP #HOME (or POP #HOME) to restore your home directory to its previous
identity, the last copy pushed.
Use #SET #HOME (or SET VARIABLE #HOME) to define a directory variable as
your home directory.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-191
false
= zero
enclosure
is an enclosure containing a THEN or an ELSE label. Each label is optionally
followed by text that typically consists of one or more functions that can be
executed if the option is chosen.
Result
If the expression evaluation is true, #IF returns the part of the enclosure labeled
|THEN|, if it exists. If the expression is evaluated as being false, #IF returns the part of
the enclosure labeled |ELSE|, if it exists. Any label not chosen is ignored.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-192
Examples
1. The macro, furd, outputs each of its arguments on a separate line:
[#DEF furd MACRO |BODY|
== Output current argument
#OUTPUT %1%
== Test for more arguments
[#IF NOT [#EMPTY %2 TO *%] |THEN|
furd %2 TO *% == Call self without 1st arg
]
]
2. This example illustrates the use of a numeric expression:
[#IF 3 | THEN | . . .
3. This example illustrates the use of a variable name containing a decimal number:
#SET var 3
[#IF var | THEN | . . .
4. This example illustrates the use of an arithmetic expression enclosed in
parentheses:
#SET var 4
[#IF (var-1 = 3) | THEN | . . .
5. This example shows an #IF with a contingent control path, to be taken if the
numeric expression is false:
#SET tversion [#TACLVERSION]
#CHARGETV tversion tgeneric 1 TO 6
[#IF tgeneric '<' "T9205C" |THEN|
SINK [#LOAD /KEEP 1/ $vol.subvol.firstlib]
.
.
.
|ELSE|
ATTACHSEG SHARED mysegf :mydir
USE :mydir
]
6. This example illustrates an #IF with no enclosure, deleting the result of
#ARGUMENT while still allowing #ARGUMENT to accomplish its action, assigning
the argument value to NUM:
#IF [#ARGUMENT /VALUE num/ NUMBER]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-193
Result
#IN returns the name of the file currently being used for input by TACL.
Considerations
At TACL startup time, #IN contains the name of the file currently being used as the
TACL IN file. This file is called the primary IN file. To temporarily receive
commands from an alternate source, push #IN and set #IN to another file or
device. To restore the primary IN file, pop #IN.
The contents of the #IN built-in variable determine the file or process from which
TACL reads commands.
TACL can store two IN file settings:
At startup time, the #IN built-in variable contains the name of the file currently
in use as the TACL IN file. For an interactive terminal, #IN is initialized to the
name of your home terminal. This is considered the primary IN file. You cannot
permanently change the IN file for TACL; that is, the primary IN file always
remains the same.
When you set #IN to a file other than the primary file, this file is known as the
current IN file.
The default IN file for processes run by TACL is not affected by #IN; it remains
associated with the original TACL IN file. You can, however, use #INPUT or
#INPUTV with the current IN file established by #SET #IN.
When you use #SET #IN, it does not take effect until the next time TACL prompts
for a command. Therefore, if you include a #SET #IN in a macro or routine, lines
are not read from the new IN file until all lines resulting from the macro or routine
have been processed.
To set #IN to a disk file, TACL must allocate one of its block buffers internally.
Because these block buffers are large and must be allocated from the first 64,000
bytes in the TACL address space, there are only four of them. (Other consumers of
these blocks include the #OUT and #REQUESTER built-in functions.)
Any error, including EOF, on a pushed #IN variable causes #IN to be popped at
once. Any other error or break occurring while #IN is pushed causes all but the
bottom level to be popped from #IN.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-194
You can set #IN without first pushing it. This feature, in conjunction with an
equivalent one in #OUT, allows you to run TACL as a server, yet be able to
take over a terminal as though TACL had been run on the terminal in the usual
way.
When you #SET #IN without pushing it, TACL responds to the BREAK key if
the device to which you set #IN supports BREAK.
The value of #IN is the default IN file for all processes started while #IN is set
in this way.
You can revert to reading commands from $RECEIVE by setting #IN to
nothing.
Use #PUSH #IN (or PUSH #IN) to save the name of the currently open TACL IN
file.
Use #POP #IN (or POP #IN) to restore the last IN file name pushed.
Use #SET #IN (or SET VARIABLE #IN) to name the file to be used by TACL as its
IN file.
Example
Assuming #INFORMAT is set to TACL and your current IN file is your terminal, the
following displays your terminal name:
67> #OUTPUT [#IN]
$DECAY
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-195
Result
#INFORMAT returns the current #INPUT formatting mode-PLAIN, QUOTED, or TACL.
Considerations
#INFORMAT applies only to input read from the IN file, not to any other input data.
The default format for macro or routine files and function libraries is TACL format;
to change this setting, use a ?FORMAT directive.
PLAIN format is always in effect for #REQUESTERs, #SERVERs, and #DELTA file
operations, and for the IN option on #SET and SET.
When you first log on, #INFORMAT is initialized to PLAIN.
To change the default for your TACL session, use a #SET #IN statement. You can
also specify the IN file when you start a TACL process.
To read information from the current IN file, use the #INPUT built-in function.
To set or obtain the current formatting mode for the TACL OUT file, use the
#OUTFORMAT built-in variable.
If #INFORMAT is TACL, any characters that are converted to internal format on
input are stored with a tilde as a prefix. These characters include {, }, ==, [, ], and |.
#INFORMAT can affect how #ARGUMENT interprets arguments. For more
information, refer to the description of #ARGUMENT Built-In Function on
page 9-21.
Use #PUSH #INFORMAT (or PUSH #INFORMAT) to save a copy of the current
#INPUT formatting mode.
Use #POP #INFORMAT (or POP #INFORMAT) to restore the last #INPUT
formatting mode pushed.
Use #SET #INFORMAT (or SET VARIABLE #INFORMAT) to establish the current
formatting mode.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-196
PLAIN
specifies that TACL should not translate characters read from IN, but should
consider everything to be ordinary text; for example, braces and double equal
signs are read as such and are not interpreted as comments in PLAIN mode.
QUOTED
causes TACL to translate metacharacters as if the formatting mode were
TACL, but if text containing such characters is enclosed in quotation marks,
TACL treats embedded metacharacters as if they were ordinary text (no tildes
are needed). The #SET and #SETV built-in functions operate in different ways:
#SET treats quotes as plain text; #SETV does not include the quotes (see
Examples).
TACL
causes TACL to translate the metacharacters [ and ] (square brackets), { and }
(braces), | (vertical line), == (double equals), and ~ (tilde) into internal notation.
TACL reads square brackets as the beginning and ending of an invocation. A
vertical line indicates a label in an enclosure. TACL reads braces and double
equals as comments.
Using a tilde causes TACL to interpret the next character as plain text, rather
than a delimiter; for example, TACL reads ~[ as an ordinary open square
bracket, rather than the beginning of an invocation. To use a tilde character as
text, double it (~~). The tilde has no effect on its own, but only in conjunction
with other characters.
When using the TACL format, you can put several commands on a single line
by separating the commands with a tilde and a semicolon (~;). TACL translates
these into internal end-of-line characters.
You can also use a tilde and an underscore (~_) when #INFORMAT is set to
TACL. TACL translates this notation into an internal space. These metaspaces
are printed as spaces if you use the PRETTY option with #OUTFORMAT;
otherwise, they are treated as ordinary characters.
Examples
If you specify special characters in an IN file, #INFORMAT affects how TACL interprets
the characters. This sends square brackets to TEDIT:
56> TEDIT critique; SEARCH [sic]
If the command is part of an IN file and #INFORMAT is set to TACL (or QUOTED),
TACL tries to invoke SIC, considering it to be a variable, and displays an error
message. If you change the command to
57> TEDIT critique; SEARCH ~[sic~]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-197
TACL passes the brackets as text to TEDIT. Preceding any TACL metacharacter
(including the tilde character itself) with a tilde causes TACL to consider it as simple
text.
Table 9-11 lists the difference in text storage between TACL and QUOTED settings
after the variables are initialized as follows (#OUTFORMAT is set to PLAIN):
#PUSH var b
#SET b $
Table 9-11. #INFORMAT Results
TACL Operation
a$c
a$c
a$c
a[b]c
a[b]c
a~[b~]c
These examples show differences in text storage between #SETV and #SET with the
QUOTED #INFORMAT setting (#OUTFORMAT is set to PLAIN):
15> #PUSH var
16> #SET var abc[def]ghi
17> #OUTPUTV var
abc[def]ghi
18> #SETV var abc[def]ghi
19> #OUTPUTV var
abc[def]ghi
20>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-198
# IN IT T E R M B uilt-In F u nctio n
Result
#INITTERM returns nothing.
Considerations
You typically use this command when an application program leaves your terminal
in an abnormal state.
The #INITTERM built-in function calls the SETMODE operating system procedure,
function 28. For information about setting device attributes, see the description of
SETMODE setting for terminals in the Guardian Users Guide and the description
of the SETMODE procedure in the Guardian Procedure Calls Reference Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-199
Result
#INLINEECHO returns 0 if echoing is disabled, -1 if it is enabled.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-200
# IN L IN E E O F B uilt-In F u nctio n
Result
#INLINEEOF returns nothing.
Considerations
TACL waits until the inline process prompts for input then sends an EOF indication
to that process.
Use of #INLINEEOF when no inline process exists causes an error.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-201
# IN L IN E O U T B u ilt-In V a ria b le
Result
#INLINEOUT returns 0 if inline process output copying is disabled, -1 if it is enabled.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-202
Result
#INLINEPREFIX returns the character or characters that make up the current inline
prefix, if any.
Considerations
The default prefix is a null value (no prefix). For efficiency, you should
leave the prefix set to nothing when you are not using the INLINE facility.
You must not use #SET as the prefix; doing so prevents you from
changing it to anything else.
For additional information and examples showing the use of #INLINEPREFIX, refer
to the TACL Programming Guide.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-203
# IN L IN E P R O C E S S B u ilt-In V a ria b le
Result
#INLINEPROCESS returns the process ID of the current inline process, if one exists; if
not, #INLINEPROCESS returns nothing.
Considerations
When you push #INLINEPROCESS, you can create another inline process only if your
total number of #REQUESTERs, implicit and explicit #SERVERs, and inline processes
is less than 100.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-204
# IN L IN E P R O C E S S B u ilt-In V a ria b le
When you pop #INLINEPROCESS (or unframe it) and its corresponding inline process
is still in existence, you can no longer communicate with that process;
TACL responds to all its I/O requests with error 66. The process is still counted
against the 100-process limit mentioned above, however, until it terminates.
Pushing and popping #INLINEPROCESS has no effect on any of the other built-in
variables related to inline processes (#INLINEECHO, #INLINEOUT,
#INLINEPREFIX, or #INLINETO).
When you first log on, #INLINEPROCESS is initialized to a null value.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-205
# IN L IN E T O B u ilt-In V a ria b le
Result
#INLINETO returns the fully qualified name of the variable level to which inline process
output is appended, if such a variable has been defined; otherwise, #INLINETO returns
nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-206
# IN P U T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-207
# IN P U T B uilt-In F u nctio n
If you omit the UNTIL option, pressing a function key or the RETURN key
terminates reading. prompt is one or more characters to be written to the
IN file as a prompt.
Consideration
TACL saves the primary IN file, set at startup time, as the default setting of the #IN
built-in variable. If you set #IN to another file, TACL stores the second file as the
current IN file. You can use the #INPUT built-in function to read from either file.
Result
#INPUT returns the line read from the input file.
Examples
This example illustrates the differences resulting from options in the reactions of
#INPUT to function keys. Each of these read operations is terminated by function key
12:
1. With no options, #INPUT provides no carriage return, so the output in this example
appears as a continuation of the input, though on the next line. Text supplied by the
function key is included with the input text:
24> #OUTPUT [#INPUT ?]
?this
thisK$%
2. Option processing provides a carriage return, so the output text appears at the
beginning of the next line. With the FUNCTIONKEY option, the identity of the
function key pressed is stored in the specified variable level:
25> #PUSH key
26> #OUTPUT [#INPUT /FUNCTIONKEY key/ ?] , [key]
?that
that , F12
3. With the UNTIL TACL option, the identity of the function key prefaces the input
text:
27> #OUTPUT [#INPUT /UNTIL TACL/ ?]
?the_other
F12 the_other
4. These statements use #INPUT to prompt a user, save the name of the function key
that terminated the input, and place the input into the history buffer:
29>
30>
31>
32>
33>
F12
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-208
# IN P U T B uilt-In F u nctio n
this is a test
OUTVAR key
OUTVAR text
HISTORY 4
If you omit the HISTORY option in the #INPUT function call, "this is a test" does not
appear in the history listing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-209
# IN P U T E O F B u ilt-In V a ria b le
Result
#INPUTEOF returns -1 if TACL reads an end-of-file; otherwise, it returns 0.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-210
Result
#INPUTV returns nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-211
The former construct is faster and is not subject to errors incurred in type-checking the
input data.
If the data from IN is longer than the data area of the STRUCT, the excess bytes
are discarded without any notification.
If the data from IN is shorter than the data area of the STRUCT, TACL sets the
entire STRUCT to its default values and then moves the supplied data into the
beginning of the data bytes of the STRUCT.
Example
This example shows the use of strings in both the HISTORYV operand and the prompt
of an #INPUTV invocation.
#PUSH indata
#INPUTV /HISTORYV " : "/ indata "History line "
The resulting dialog at the IN file appears as:
History line 43 : user input
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-212
# IN S P E C T B u ilt-In V a ria b le
Result
#INSPECT returns the current state of the inspect flag: OFF, ON, or SAVEABEND.
Considerations
H-Series Usage
The program DEBUG is not available for use on systems running H-series software.
The DEBUG command invokes a debugger, it can be Inspect, Native Inspect
(eInspect, which is not in the family of Inspect debuggers), or Visual Inspect.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-213
# IN S P E C T B u ilt-In V a ria b le
The rules about which debugger gets invoked are approximately the same as for the
RUND command. That is, if the INSPECT attribute is set ON anywhere (in the object
file during compilation, or on the TACL command line using the SET command), you
will get a debugger in the Inspect family (either Inspect or VI), unless of course neither
of these debuggers is available, and then you get the default debugger, eInspect. If
the Inspect attribute is OFF, you get Native Inspect (eInspect).
Inspect is invoked only for TNS accelerated/interpreted programs (never for TNS/E
native programs), while Visual Inspect can handle both of these. Native Inspect
handles only TNS/E native programs and snapshots.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-214
# IN T E R A C T IV E B uilt-In F u nctio n
Result
If you include the CURRENT option, #INTERACTIVE returns -1 if the current IN file is
the same as the current OUT file (the contents of #IN are the same as the contents of
#OUT); otherwise, it returns 0.
If you omit the CURRENT option, #INTERACTIVE returns -1 if the primary IN file is the
same as the primary OUT file; otherwise, it returns 0.
The primary IN and OUT files are those in effect when TACL first starts (specified by
the IN and OUT run options in the RUN command that initiates the TACL process). The
current IN and OUT files may be different from those, if #SET #IN or #SET #OUT have
been executed.
Consideration
TACL automatically determines whether it is interactive when it first starts to run.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-215
Result
#INTERPRETJULIANDAYNO returns a space-separated list of the numeric year,
month, and day.
Example
24> #OUTPUT [#INTERPRETJULIANDAYNO 2448047]
1990 6 4
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-216
Result
#INTERPRETTIMESTAMP returns a space-separated list of nine numbers, consisting
of the Julian day number, year, month, day, hour, minute, second, millisecond, and
microsecond.
Example
This example illustrates #INTERPRETTIMESTAMP output:
21> #OUTPUT [#INTERPRETTIMESTAMP [#JULIANTIMESTAMP]]
2447701 1991 6 23 22 29 42 784 566
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-217
# IN T E R P R E T T R A N S ID B uilt-In F u nctio n
Result
#INTERPRETTRANSID returns a numeric status code indicating the outcome of the
conversion:
0
Successful conversion
-2
Invalid transaction ID
Any other value indicates a TACL problem and should be reported to your service
provider.
If the numeric status is zero, it is followed by a space and a space-separated list of
these transaction-ID components:
System number
CPU number
Sequence number
Crash count
Consideration
To convert the components of a transaction ID into a single numeric transaction ID, use
the #COMPUTETRANSID built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-218
# JU L IA N T IM E S T A M P B uilt-In F u nctio n
current GMT
Result
#JULIANTIMESTAMP returns the selected GMT timestamp; if tuid-request is not
zero, the timestamp is followed by a space and the current time update ID.
Examples
This example shows #JULIANTIMESTAMP output:
22> #OUTPUT [JULIANTIMESTAMP]
211481404070538528
This example illustrates the use of four-word timestamps obtained from
#JULIANTIMESTAMP and #FILEINFO to make a decision based on the age of a file
(represented by the dummy argument %1%):
[#IF [#JULIANTIMESTAMP] - [#FILEINFO /CREATION_GMT/.%1%]
> 31536000000000 == Julian number equivalent to 1 year
|THEN|
#OUTPUT %1% is more than 1 year old. Purge it?
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-219
# K E E P B uilt-In F u nctio n
Result
#KEEP returns as its result the number of levels deleted.
Consideration
#KEEP 0 removes the variable.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-220
# K E Y S B uilt-In F u nctio n
Result
#KEYS returns a space-separated list containing the names of all defined function
keys.
Example
Assuming #INFORMAT is set to TACL, this statement displays the currently defined
keys:
14> #OUTPUT [#KEYS]
F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 SF1 SF16
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-221
# L IN E A D D R B uilt-In F u nctio n
Result
#LINEADDR returns the line number of the line that contains the specified character.
Considerations
Example
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
The invocation:
#LINEADDR var 10
returns 2; the tenth character in var, counting the end-of-line between lines 1 and 2 as
one character, is the I in line 2.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-222
#L IN E B R E A K B uilt-In F u nctio n
Result
#LINEBREAK returns nothing.
Considerations
Each logical line contains an internal end-of-line character that counts as one
byte.When you use the #LINEBREAK built-in function, TACL inserts the end-of-line
character immediately before the specified character.
If char-offset is greater than the number of characters in the line, the new endof- line is inserted immediately before the existing end-of-line.
If line-addr andchar-offset are both 1, an end-of-line is inserted at the
beginning of the variable level. If line-addr is beyond the end of the variable
level, no end-of-line is inserted.
Example
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-223
#L IN E B R E A K B uilt-In F u nctio n
The invocation:
#LINEBREAK var 2 5
causes var to contain:
ABCDEFG
HIJK
LMNOPQRST
UVWXYZ
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-224
Result
#LINECOUNT returns the number of lines in the variable level.
Example
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
The invocation:
#LINECOUNT var
returns 3.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-225
# L IN E D E L B uilt-In F u nctio n
Result
#LINEDEL returns nothing.
Considerations
If you use TO, the line specified by line-addr-2 is included in the deletion: That
is, x TO y is equivalent to x FOR (y-x)+1.
If you use TO and line-addr-1 is greater than line-addr-2, no deletion
occurs.
If you omit both FOR and TO, TACL deletes the line specified by line-addr-1.
Examples
Any part of the specified deletion that lies beyond the end of the variable level is
ignored.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-226
# L IN E D E L B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-227
#L IN E F IN D B uilt-In F u nctio n
Result
#LINEFIND returns the number of the line in which text begins. If text is not found, or if
text is empty, #LINEFIND returns zero.
Considerations
If line-addr is past the end of the variable level, #LINEFIND returns zero.
A text specification can include internal end-of-line characters if the entire
invocation is enclosed in square brackets, but leading and trailing spaces and endof- lines are ignored.
The search begins immediately at the line number specified. If you make repeated
calls to this function, using the result of each as a starting point for the next, you
must add 1 to that result before supplying it to a subsequent call.
If line-addr is empty, #LINEFIND returns zero.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-228
#L IN E F IN D B uilt-In F u nctio n
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. The invocation:
#LINEFIND var 1 IJK
returns 2; the first occurrence of IJK starting in or after line 1 is in line number 2.
2. The invocation:
#LINEFIND var 2 IJK
returns 2; the first occurrence of IJK is in the specified starting line, line 2.
3. The invocation:
#LINEFIND var 3 IJK
returns 0; there are no occurrences of IJK starting in or after line 3.
4. The invocation:
#LINEFIND var 1 FOO
returns 0; there are no occurrences of FOO anywhere in var.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-229
# L IN E F IN D R B uilt-In F u nctio n
Result
#LINEFINDR returns the number of the line in which text begins. If text is not found or
text is empty, #LINEFINDR returns zero.
Considerations
If line-addr is past the end of the variable level, #LINEFINDR starts the search
at the end of the contents of the variable.
A text specification can include internal end-of-line characters if the entire
invocation is enclosed in square brackets, but leading and trailing spaces and endof- lines are ignored.
The search includes all of the specified line. The search finds a match if the
matching text begins anywhere within, or before, that line (even if the text extends
beyond the line). If you make repeated calls to this function, using the result of one
call as a starting point for the next, you must subtract one from that result before
using it in a subsequent call. This procedure avoids finding the same text again.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-230
# L IN E F IN D R B uilt-In F u nctio n
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. The invocation:
#LINEFINDR var 3 IJK
returns 2; the nearest occurrence of IJK beginning in or before line 3 is in line 2.
2. The invocation:
[#LINEFINDR var 2 T
UV]
returns 2; though the text T(end-of-line)UV carries over to line 3, it begins in line 2.
3. The invocation:
#LINEFINDR var 4 FOO
returns 0; there are no occurrences of FOO anywhere in var.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-231
# L IN E F IN D R V B uilt-In F u nctio n
Result
#LINEFINDRV returns the number of the line in which string begins. If string is not
found, or if string is empty, #LINEFINDRV returns zero. If variable-level is empty,
then #LINEFINDRV returns zero.
Considerations
Ifline-addr is past the end of the variable level, #LINEFINDRV starts the search
at the end of the contents of the variable.
One trailing end-of-line in string is ignored. Leading and trailing spaces are
preserved, as are all other end-of-lines.
The search includes all of the specified line. The search finds a match if the
matching string begins anywhere within, or before, that line (even if the string
extends beyond the line). If you make repeated calls to this function, using the
result of one call as a starting point for the next, you must subtract one from that
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-232
# L IN E F IN D R V B uilt-In F u nctio n
result before using it in a subsequent call. This procedure avoids finding the same
string again.
Each line break contains an internal end-of-line character that counts as one byte.
For variables that contain TACL statements, each square bracket ([,]), vertical bar
(|), or tilde-space combination (~_) uses two bytes, including unprintable
characters that are subject to change from one TACL RVU to another. Other
characters use one byte.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
and that var2 is a variable level containing:
IJK
1. Either of the invocations:
#LINEFINDRV var 3 "IJK" or #LINEFINDRV var 3 var2
returns 2; the nearest occurrence of IJK beginning in or before line 3 starts in line
2.
2. The invocation:
#LINEFINDRV var 2 "UVW"
returns 0; there are no occurrences of UVW beginning in or before line 2.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-233
#L IN E F IN D V B uilt-In F u nctio n
Result
#LINEFINDV returns the number of the line in which string begins. If string is not found
or the string is empty, #LINEFINDV returns zero. If variable-level is empty, then
#LINEFINDV returns zero.
Considerations
If line-addr is past the end of the variable level, #LINEFINDV returns zero. The
search starts immediately at the beginning of the line specified. If you make repeated
calls to this function, using the result of each as a starting point for the next, you must
add 1 to that result before supplying it to a subsequent call.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-234
#L IN E F IN D V B uilt-In F u nctio n
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
and that var2 is a variable level containing:
IJK
1. Either of the invocations:
#LINEFINDV var 1 "IJK" or #LINEFINDV var 1 var2
returns 2; the first occurrence of IJK starting in or after line 1 is in line 2.
2. Either of the invocations:
#LINEFINDV var 2 "IJK" or #LINEFINDV var 2 var2
returns 2; the first occurrence of IJK is exactly at the starting point, the beginning of
line 2.
3. Either of the invocations:
#LINEFINDV var 3 "IJK" or #LINEFINDV var 3 var2
returns 0; there are no occurrences of IJK starting in or after line 3.
4. The invocation:
#LINEFINDV var 1 "FOO"
returns 0; there are no occurrences of FOO anywhere in var.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-235
#L IN E G E T B uilt-In F u nctio n
Result
#LINEGET returns as its result the copied lines.
Considerations
If you use TO, the line specified by line-addr-2 is included in the copy; that is,
x TO y is equivalent to x FOR (y-x)+1.
If you use TO and line-addr-1 is greater than or equal to line-addr-2, or if
you use FOR and line-count is zero, no copying occurs.
If you omit both FOR and TO, one line is copied.
Any part of the specified copy that lies beyond the end of the variable level is
ignored.
If #LINEGET is to return more than one line, you must enclose in square brackets
the invocation of the function that obtains that result.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-236
#L IN E G E T B uilt-In F u nctio n
Examples
Assume that var is a variable level containing:
THE QUICK BROWN
FOX JUMPED OVER
THE LAZY DOG
TWICE A DAY
EXCEPT TUESDAYS.
1. The invocation:
#LINEGET var 2
returns:
FOX JUMPED OVER
2. Either of the invocations:
#LINEGET var 2 TO 4 or #LINEGET var 2 FOR 3
returns:
FOX JUMPED OVER
THE LAZY DOG
TWICE A DAY
Therefore, a function invocation producing that result must be enclosed in square
brackets:
[#OUTPUT [#LINEGET var 2 FOR 3]]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-237
#L IN E G E T V B uilt-In F u nctio n
Result
#LINEGETV returns nothing.
Considerations
If you use TO, the line specified by line-addr-2 is included in the copy: That is,
x TO y is equivalent to x FOR (y-x)+1.
If you use TO and line-addr-1 is greater than or equal to line-addr-2, or if
you use FOR and line-countis less than one, no copying occurs.
If you omit both FOR and TO, one line is copied.
Any part of the specified copy that lies beyond the end of string is ignored.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-238
#L IN E G E T V B uilt-In F u nctio n
Examples
Assume that var is a variable level containing:
THE QUICK BROWN
FOX JUMPED OVER
THE LAZY DOG
TWICE A DAY
EXCEPT TUESDAYS.
Either of the invocations:
#LINEGETV var var2 2 TO 3 or #LINEGETV var var2 2 FOR 4
set var2 to:
FOX JUMPED OVER
THE LAZY DOG
The invocation:
#LINEGETV var var2 3
sets var2 to:
THE LAZY DOG
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-239
#L IN E IN S B uilt-In F u nctio n
Result
#LINEINS returns nothing.
Considerations
A text specification can include internal end-of-lines if you enclose the entire
invocation in square brackets, but leading and trailing spaces and end-of-lines are
ignored.
If line-addrr is beyond the end of the variable level, the text is appended to the
end of the variable level, starting on a new line.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
1. The invocation:
#LINEINS var 3 NEW TEXT
causes var to contain:
ABCDEFG
HIJKLMNOPQRST
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-240
NEW TEXT
UVWXYZ
2. The invocation:
[#LINEINS var 3 NEW
TEXT]
causes var to contain:
ABCDEFG
HIJKLMNOPQRST
NEW
TEXT
UVWXYZ
3. The invocation:
#LINEINS var 100 NEW TEXT
causes var to contain:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
NEW TEXT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-241
#L IN E IN S B uilt-In F u nctio n
#L IN E IN S V B uilt-In F u nctio n
Result
#LINEINSV returns nothing.
Considerations
Leading and trailing spaces in string are preserved, as are all end-of-lines.
If line-addr is beyond the end of the variable level, string is appended to the end
of the variable level, starting on a new line.
Examples
Assume that var is a variable level containing:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
and that var2 is a variable level containing:
NEW
TEXT
1. The invocation:
#LINEINSV var 3 var2
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-242
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-243
#L IN E IN S V B uilt-In F u nctio n
#L IN E JO IN B uilt-In F u nctio n
Result
#LINEJOIN returns nothing.
Considerations
If line-addr is equal to or greater than the number of the last line, no joining
occurs.
Lines are joined with no intervening new character.
You can use #CHARDEL to delete an end-of-line at a specific character position.
Examples
Assume that var is a variable level containing this:
ABCDEFG
HIJKLMNOPQRST
UVWXYZ
The invocation:
#LINEJOIN var 2
causes var to contain:
ABCDEFG
HIJKLMNOPQRSTUVWXYZ
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-244
# LO A D B uilt-In F u nctio n
Result
#LOAD returns a space-separated list containing the names of the variables loaded. If
you specify the LOADED option, however, #LOAD returns nothing.
Considerations
The LOADED option is especially useful for loading libraries containing large
numbers of variables (so many that a text buffer overflow error results when they
are placed in the result of #LOAD).
If you need to include a blank line (often useful in DELTA type variables), use the
?BLANK directive. ?BLANK causes the loader to insert a blank line in the variable
level.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-245
# LO A D B uilt-In F u nctio n
To include lines beginning with question marks, (for example, you might be loading
DDL commands into a variable level for later use as the IN variable for a DDL run),
double the question mark (??). The first question mark and any spaces adjacent to
it are discarded and the remainder of the line is treated as text.
For each ?SECTION name type directive in a library file, TACL pushes a variable
named name, sets its type to type, and sets its contents to text (all the text that
follows the ?SECTION directive, until the next directive or the end of the library
file). If the variable name already exists, TACL pushes the variable and puts text in
the new top level.
#LOAD reads data from a library file in TACL format unless the file contains a
?FORMAT PLAIN or ?FORMAT QUOTED directive to specify otherwise. If
changed, the format reverts to TACL at the next ?SECTION directive.
The definition of a STRUCT in a library file cannot contain square brackets; the
body of the structure must not be on the same line as the ?SECTION directive.
If you load a variable that is already loaded, TACL pushes the variable and creates
a new variable level.
To obtain a list of variables loaded into your home directory, use the VARIABLES
command or the #VARIABLES built-in function.
To obtain detailed information about a variable in your home directory, use the
VARINFO command or the VARIABLEINFO built-in function.
To delete a variable, use the KEEP command, the #KEEP built-in function, or the
KEEP option of the #LOAD built-in function (to delete and load a variable
simultaneously):
#SET rslt [#LOAD /KEEP 1/ TESTS]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-246
# LO A D B uilt-In F u nctio n
Examples
Following are some examples of ?SECTION directives in library files that can be
processed by #LOAD:
?SECTION versnum TEXT
== Version of this library
14OCT91
?SECTION setmacro MACRO
== Creates a macro (%1%) defined by text (%2 to *%)
[#DEF %1% MACRO |BODY|%2 to *%]
?SECTION setvar ALIAS
== Defines a variable
SETMACRO
?SECTION nocommas MACRO
== Turns comma-separated list into space-separated list
[#DELTA /COMMANDS nocommas_d/ %*%]
?SECTION nocommas_d DELTA
== Engine for NOCOMMAS
J<:S,$;-DI $>
?SECTION inventory STRUCT
BEGIN
INT item;
INT price;
INT quantity;
END;
?SECTION obsolete^items STRUCT
LIKE inventory;
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-247
# LO C K IN F O B uilt-In F u nctio n
Result
#LOCKINFO returns a file-system error code indicating the outcome of the operation. If
the code is 0 (no error) or 45 (file is full-no error otherwise), it is followed by a space
and the tag to be passed in the next call to #LOCKINFO.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-248
# LO C K IN F O B uilt-In F u nctio n
Consideration
For D-series programs, use the #FILEGETLOCKINFO built-in function.
Example
This routine accepts a volume name and reports all locks for that volume.
?SECTION looklock ROUTINE
#FRAME
== Define buffer into which #LOCKINFO puts lock information.
[#DEF buffer STRUCT
BEGIN
STRUCT lib;
BEGIN
BYTE type;
BYTE keylen;
INT misc;
CHAR svol^file(0:15);
INT numlab;
INT2 laboff; == byte offset of 1st labinfo entry
BYTE keyval(0:255);
INT2 recaddr REDEFINES keyval;
== Be sure there is space for at least 1 labinfo entry.
== More might fit if keylen < 256.
FILLER 12;
END; == lib
STRUCT generic REDEFINES lib;
BEGIN
BYTE onechar (0:293);
END;
END; == buffer
] == end #DEF
== Define structure for one labinfo entry.
== One entry at a time is copied here from buffer.
[#DEF labinfo STRUCT
BEGIN
INT misc;
CRTPID locker;
TRANSID translocker REDEFINES locker;
INT reserved;
END; == labinfo
] == end #DEF
== Get byte length of labinfo STRUCT
#PUSH labinfolen
#SET labinfolen [#VARIABLEINFO /LEN/ labinfo]
== Define macro to show information about one locked &
resource (a file or a record).
[#DEF display_lib MACRO |BODY|
#OUTPUT
== Get interesting values from buffer.
#SET type [buffer:lib:type]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-249
#SET
#SET
#SET
#SET
#SET
# LO C K IN F O B uilt-In F u nctio n
keylen [buffer:lib:keylen]
fname [vol].[buffer:lib:svol^file(0:7)]
fname [fname].[buffer:lib:svol^file(8:15)]
numlab [buffer:lib:numlab]
laboff [buffer:lib:laboff]
== Display them.
#OUTPUT type: [buffer:lib:type]
#OUTPUT keylen: [keylen]
#OUTPUT laboff: [laboff]
== Is it a record lock or a file lock?
[#IF ([buffer:lib:type]) |THEN|
#OUTPUT RECORD LOCK on [fname]
[#IF (keylen = 0) |THEN|
#OUTPUT ID: [buffer:lib:recaddr]
|ELSE|
#OUTPUT ID: [buffer:lib:keyval(0:[#compute (keylen-1)])]
]
|ELSE|
#OUTPUT FILE LOCK on [fname]
]
== Show number of lockers/waiters.
#OUTPUT [numlab] locks and waits for [fname]
] == end DISPLAY_LIB macro
== Define macro to display all labinfo entries returned for &
one locked resource (a file or a record).
[#DEF display_lab MACRO |BODY|
== Loop for each labinfo entry. There are [numlab] entries.
#SET count 0
[#LOOP |WHILE| (count < numlab) |DO|
== Compute location of current labinfo entry.
#SET start [#COMPUTE laboff + (labinfolen * count)]
#SET stop [#COMPUTE start + labinfolen-1]
== Copy entry from buffer to labinfo structure.
#SETBYTES labinfo buffer:generic:onechar([start]:[stop])
== Display entry.
#OUTPUTV labinfo
== Increment entry number.
#SET count [#COMPUTE count + 1]
] == end #LOOP
] == end DISPLAY_LAB macro
== Initialize variables
#PUSH vol err tag
#PUSH type keylen fname numlab laboff
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-250
# LO C K IN F O B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-251
#L O G O F F B uilt-In F u nctio n
Result
#LOGOFF returns nothing.
Considerations
When you log off, any processes that you started continue to run.
Any macro or routine running at the time #LOGOFF occurs terminates
immediately. A subsequent LOGON does not restart it. For example:
#FRAME
...
#LOGOFF
#UNFRAME
causes the frame counter to remain in its incremented condition because
#UNFRAME is not executed.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-252
#L O G O F F B uilt-In F u nctio n
If you use the #LOGOFF function while working through a modem, the modem
disconnects (unless the ancestor of the TACL process is running in another
system).
If the ancestor of your current TACL process is a process running in another
system and you enter the LOGOFF command, the current TACL process is deleted
and control returns to the ancestor process. This message is displayed:
Exiting from TACL on \node-name
If you are accessing a remote node through a modem on your local node, TACL
does not issue a modem disconnect.
Any process that tries to use your variables after you log off receives error 66 on its
I/O requests.
If your TACL is interactive and you are using a HP Tandem 6520 or 6530 terminal
emulator, and TACL is configured to clear the screen as a security measure (the
default), it does so when you log off. You can override the automatic screen
clearing with the NOCLEAR option. Conversely, if TACL is configured to omit
automatic screen clearing, you can use the CLEAR option to clear the terminal
screen.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-253
#L O O K U P P R O C E S S B uilt-In F u nctio n
specifier
is one of these process identifiers:
[\node-name.]{$process-name | cpu,pin }
entry-number [ \node-name ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-254
#L O O K U P P R O C E S S B uilt-In F u nctio n
\node-name
is the system where the process is running.
$process-name
is the name of the process.
cpu,pin
is the CPU,PIN of the entry.
entry-number [ \node-name ]
is an entry number in the DCT for the specified system. If you omit\nodename, the current default is used.
Result
#LOOKUPPROCESS returns a space-separated list of the selected information about
the DCT entry. The information is listed in the order in which the request options
appear.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-255
#L O O P B uilt-In F u nctio n
= a nonzero value
false
= zero
| DO | [ text ]
returns text, typically a sequence of one or more functions to be repeatedly
executed while numeric-expression is true, or until numericexpression becomes true. If you omit text, #LOOP merely waits until the
specified criterion is met.
Result
#LOOP evaluates the WHILE or UNTIL text and tests it for inequality to zero.
Depending on the result of that test, #LOOP either returns the DO text (typically TACL
statements for execution) and repeats the test, or terminates.
Considerations
The WHILE/DO version of #LOOP evaluates the expression first; if the expression
is true, it executes the DO text. It continues to do so as long as the expression is
true. The |WHILE| label must precede the |DO| label.
The DO/UNTIL version of #LOOP executes the DO text before evaluating the
expression; if the expression is false, #LOOP performs another iteration. #LOOP
continues its iterations until the expression becomes true. This version always
makes at least one loop, even if the expression was initially true. The |DO| label
must precede the |UNTIL| label.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-256
# M A T C H B uilt-In F u nctio n
text
is a character sequence to be compared to template.
Result
#MATCH returns -1 if the text satisfies the rules for the template; otherwise, it returns
0.
Considerations
To compare one string with another string, use the #COMPAREV built-in function.
(Strings can contain embedded spaces.).
Note. Use of a large number of wild-card characters (*,?) can use significant processor
resources.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-257
#M O M B uilt-In F u nctio n
Result
If TACL is a named process and the backup does not exist, the result is blank.
If TACL is a named process and the backup does exist, the result is the process
name itself.
If TACL is an unnamed single process, the result is the TACL ancestor.
Consideration
To obtain the identity of the job ancestor of your TACL process, if your TACL process is
part of a batch job, use the #MYGMOM built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-258
# M O R E B uilt-In F u nctio n
Result
#MORE returns -1 if there are more arguments, 0 if there are none remaining.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-259
# M Y G M O M B uilt-In F u nctio n
Result
#MYGMOM returns the process name, or the CPU number and process identification
number, of the TACL process job ancestor, if there is one; otherwise, it returns nothing.
Consideration
To obtain the process name, or CPU number and process identification number, of the
creator or backup process associated with your TACL process, use the #MOM built-in
function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-260
# M Y P ID B uilt-In F u nctio n
Result
#MYPID returns the CPU number and PIN of your TACL process. If it is a process pair,
#MYPID returns the CPU,PIN of the primary process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-261
#M Y S Y S T E M B uilt-In F u nctio n
Result
#MYSYSTEM returns the node name.
Consideration
#MYSYSTEM is not affected by #SYSTEM. Although you might be conducting
operations on another system, your TACL continues to run on the system on which it
was started.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-262
#M Y T E R M B u ilt-In V a ria b le
Result
#MYTERM returns your current TACL home terminal name.
Considerations
When you first log on, #MYTERM is initialized to the name of your home terminal.
Use #MYTERM to direct Inspect and Debug output to your home terminal from a
process running at a different terminal.
Use #MYTERM to change the home terminal name for backup processes.
When a process abends, TACL notifies the parent TACL process in addition to the
home terminal.
The #MYTERM display includes the node name only if the home terminal is
running on a remote system or if the TACL defaults contain a node name.
Use #PUSH #MYTERM (or PUSH #MYTERM) to save a copy of your current
TACL home terminal name.
Use #POP #MYTERM (or POP #MYTERM) to restore your current TACL home
terminal to the last home terminal name pushed.
Use #SET #MYTERM (or SET VARIABLE #MYTERM) to define your current TACL
home terminal name.
The syntax of #SET #MYTERM is:
#SET #MYTERM home-term
home-term
is the terminal name or process name that is to become your new home
terminal. This does not affect the location to which TACL writes its output or
from which it reads commands, but it does affect the home terminal
designation for processes TACL starts.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-263
#M Y T E R M B u ilt-In V a ria b le
Examples
1. This example shows how to display the contents of #MYTERM:
10> #MYTERM
#MYTERM expanded to:
$TG0.$G04
2. This example pushes, sets, and pops the value of #MYTERM:
11> #PUSH MYTERM
12> #MYTERM
#MYTERM expanded to:
$TG0.$G04
13> #SET #MYTERM $ZTNT.#PTY46
14> #MYTERM
#MYTERM expanded to:
$ZTNT.#PTY46
15> #POP #MYTERM
16> #MYTERM
#MYTERM expanded to:
$TG0.#G04
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-264
# N E W P R O C E S S B uilt-In F u nctio n
Result
If you specify NOWAIT, #NEWPROCESS returns the name of the created process,
if it is a named process. If it is unnamed, it returns its CPU,PIN.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-265
# N E W P R O C E S S B uilt-In F u nctio n
ABEND
The process ended abnormally (as the result of an error trap, for
example).
CPU
NET
If TACL is awakened by a WAKE message (code 20) while waiting for completion
of the created process, #NEWPROCESS returns WAKE.
If you press the BREAK key while #NEWPROCESS is waiting, it returns nothing.
Considerations
These conditions apply to the use of the #NEWPROCESS built-in function:
When a process terminates, the operating system sends TACL a process deletion
message that contains completion information. TACL places that information in the
variables :_COMPLETION (C-series format) and :_COMPLETION^PROCDEATH
(D-series format), if those variables exist. (For additional information about
completion codes, see Section 5, Statements and Programs.)
When running a process that is to communicate with TACL (such as by setting IN
or OUT to the TACL process name, or by using TACL variables in INV or OUTV, or
by using the INLINE feature), be careful to coordinate TACL functions that enable
the communication (such as #IN or #OUT) with the counterpart mechanisms in that
process. Deadlock conditions can result if TACL tries to open a process for
communication at the same time that process is trying to open TACL for
communication.
In NOWAIT mode, TACL does not wait for the process to finish, but prompts the
terminal for the next command immediately. TACL accesses the terminal in
conversational mode. Some processes, such as TEDIT, access the terminal in
page mode. Two processes cannot share a terminal when one uses conversational
mode and the other uses page mode.
TACL allows IN and OUT files to be DEFINE names, and passes them to the
process being executed. The process is responsible for handling the DEFINEs.
TACL allows TERM names to be DEFINE names, and passes them to the process
being executed.
If you start a TACL process with HIGHPIN OFF, any processes started by that
TACL process run at a low PIN by default.
The #NEWPROCESS built-in function returns the node name only if the process
was started on a remote node.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-266
# N E W P R O C E S S B uilt-In F u nctio n
These conditions apply to the use of the RUN command for starting TACL processes:
TACL will not be able to detect the end of the INLINE process.
The output displayed might not be synchronized with the command entered
using the inline prefix.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-267
# N E X T F IL E N A M E B uilt-In F u nctio n
Result
#NEXTFILENAME returns the name of the located file.
Consideration
If you omit file-name, #NEXTFILENAME returns the first file in the current default
volume and subvolume.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-268
#O P E N IN F O B uilt-In F u nctio n
Read/write
Read-only
Write-only
BACKUP
returns the CPU,PIN of the backup process, if there is one and that process
has
the file open; otherwise, it returns nothing.
EXCLUSION
returns the exclusion specification under which the file or device was opened:
0
Shared
Exclusive
Protected
FILENAME
returns the name of the file opened (can be useful when the argument is a disk
name).
PRIMARY
returns the CPU,PIN of the primary process.
PROCESSID
returns the process name of the opening process, if the process is named;
otherwise, it returns the CPU,PIN of that process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-269
#O P E N IN F O B uilt-In F u nctio n
SYNCDEPTH
returns the sync depth with which the file or device was opened.
file-name or device-name
identifies the file or device for which information is desired. Each call to
#OPENINFO returns information about a single opening of the file or device.
tag
is a number identifying the particular opening for which information is wanted. A
zero value obtains information about the first opening; #OPENINFO includes in its
result the tag value to be used to get information about the next opening in
sequence.
Result
#OPENINFO returns a file-system code indicating the outcome of the operation:
0
Success
No (more) openings
Other file errors may be returned. See the Guardian Procedure Errors and Messages
Manual for the meanings of such messages.
If the result is 0, it is followed by a space, then the tag to be passed in the next call to
#OPENINFO, then another space, and finally a space-separated list of the information
requested by the options you supplied, in the order requested.
Considerations
Openings are not reported in any defined order. In particular, when #OPENINFO is
retrieving information about all openings of a disk volume, the openings for any
one file are not grouped together in the sequence of calls.
Because the BACKUP option may return nothing, you should specify it as the last
option to prevent confusion in reading the information list.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-270
#O P E N IN F O B uilt-In F u nctio n
Example
This routine accepts a file or device name and processes (simulation only) all the
openings of that file or device.
?SECTION lookopen ROUTINE
#FRAME
== Make some temps
#PUSH searchname error tag processid primary backup
== Get the argument
#IF [#ARGUMENT/VALUE searchname/ FILENAME DEVICE]
#IF [#ARGUMENT END]
== Start with first opening
#SET tag 0
== Loop until error
[#LOOP |DO|
== Get information using previous tag
[#SETMANY
error tag processid primary backup
,
[#OPENINFO/PROCESSID,PRIMARY,BACKUP/ [searchname] [tag]]
]
== Check for error
[#IF (error = 0) |THEN|
== No error; process the open-information
...
] { End IF }
|UNTIL| (error <> 0)
] { End LOOP }
== Error 1 is normal termination
[#IF (error <> 1) |THEN|
#OUTPUT Error [error] on [searchname]
]
== Clean up
#UNFRAME
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-271
#O U T B u ilt-In V a ria b le
Result
#OUT returns the name of the current TACL OUT file.
Considerations
When you first log on to an interactive TACL, #OUT is initialized to the name of your
home terminal.
You cannot permanently change the primary TACL OUT file; that is the primary OUT
file always remains the same. You must push #OUT before you set it to a new OUT
file.
Setting #OUT to a disk file requires that TACL allocate one of its block buffers
internally. Because these blocks are large and must be allocated from the first 64K
bytes of the TACL address space, there are only four of them. (Other consumers of
these blocks buffers are #IN and #REQUESTER.)
When TACL has been started with its IN set to $RECEIVE, these guidelines apply:
You can set #OUT without first pushing it. This feature, in conjunction with an
equivalent one in #IN, allows you to run TACL as a server yet be able to take over
a terminal as though TACL had been run on the terminal in the usual way.
The value of #OUT is the default OUT file for processes started while #OUT is set
in this way.
You can revert to sending output as a REPLY to $RECEIVE by setting #OUT to a
null value.
To set or obtain the name of the current IN file, use the #IN built-in variable.
Lines read from the current IN are appropriately echoed to the current OUT. The
default OUT file to processes started by TACL is not affected by #OUT; the default
remains associated with the original TACL OUT file.
When communicating with a process, be careful to coordinate functions that
enable the communication (such as #IN or #OUT) with the counterpart
mechanisms in that process (such as IN or OUT referring to the TACL process
name). Deadlock conditions can result if TACL tries to open a process for
communication at the same time that process is trying to open TACL for
communication.
Use #PUSH #OUT (or PUSH #OUT) to save a copy of the current OUT file name.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-272
#O U T B u ilt-In V a ria b le
Any error while pushing OUT causes #OUT to be popped at once. Any other error
or break occurring while #OUT is pushed causes all but the bottom level of #OUT
to be popped before the error message is printed.
Use #POP #OUT (or POP #OUT) to restore the last OUT file name pushed.
Use #SET #OUT (or SET VARIABLE #OUT) to set the name of the file to be used
by TACL for OUT. Before setting #OUT, you must #PUSH #OUT (unless IN is set
to $RECEIVE, as noted previously).
Example
This example causes TACL to write 002, 040, and 120 to the file OUTFILE, and then
the OUT file reverts to its previous status:
#PUSH #OUT
...
#SET #OUT outfile
#OUTPUT /HOLD,COLUMN 5,JUSTIFY RIGHT,WIDTH 3,FILL ZERO/ 2
#OUTPUT /HOLD,COLUMN 13,JUSTIFY RIGHT,WIDTH 3,FILL ZERO/ 40
#OUTPUT /COLUMN 21, JUSTIFY RIGHT, WIDTH 3, FILL ZERO/ 120
#POP #OUT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-273
# O U T F O R M A T B u ilt-In V a ria b le
Result
#OUTFORMAT returns the current #OUTPUT formatting mode: PLAIN, PRETTY, or
TACL.
Considerations
# O U T F O R M A T B u ilt-In V a ria b le
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-275
#O U T P U T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-276
#O U T P U T B uilt-In F u nctio n
WORDS
causes text to be treated as a space-separated list of output items, applying
the FILL, JUSTIFY, and WIDTH options to each item. Without WORDS, text is
treated as a single output item.
text
is the output item. If you omit text, #OUTPUT writes a blank line.
Result
#OUTPUT returns nothing.
Considerations
This statement outputs the first line of vara and then executes any other lines,
unless vara is a routine:
#OUTPUT [vara]
If vara is a routine, TACL interprets the contents of vara and outputs its results.
If, however, you want your output on separate lines, you can force separate lines by
specifying the COLUMN option; TACL starts a new line if there is output in the
specified column. This macro:
?TACL MACRO
#OUTPUT /COLUMN
#OUTPUT /COLUMN
#OUTPUT /COLUMN
#OUTPUT
#OUTPUT This is
#O U T P U T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-278
#O U T P U T V B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-279
#O U T P U T V B uilt-In F u nctio n
WORDS
specifies that each line of string is to be treated as a space-separated list and
that the FILL, JUSTIFY, and WIDTH options are to be applied to the individual
members of the list. Without WORDS, string is treated as a single output item.
string
is the data to be output. It is the name of an existing variable level, text enclosed
in quotation marks, or a concatenation of such entities. The concatenation operator
is '+' (the apostrophes are required).
Result
#OUTPUTV returns nothing.
Considerations
If you supply options, they are applied to each line of string as though you had
called #OUTPUT with the same options once for each line. In particular, the last
line is the only one that can be held, as each line forces output of any previous
line.
#OUTPUTV with the /HOLD/ option is useful for constructing lines to be output
piece by piece. For example, this example illustrates how you can do this by
putting the commands into an edit-format file and then invoking the file.
?TACL MACRO
#PUSH vara
#SET vara What a
#OUTPUTV /HOLD/ vara
#SET vara fine
#OUTPUTV /HOLD/ vara
#SET vara day
#OUTPUTV vara
When you invoke the macro, the text all comes out on one line.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-280
#O U T P U T V B uilt-In F u nctio n
Example
This example shows the use of a concatenated string containing both a variable name
and quoted text as an argument to #OUTPUTV.
#PUSH termname
#SET termname [#MYTERM]
#OUTPUTV "My terminal is " '+' termname '+' " at this time."
Assuming the home terminal name is $GREEN at the time the #SET function is
executed, the following is written to the OUT file:
My terminal is $GREEN at this time.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-281
# P A R A M B u ilt-In V a ria b le
Result
#PARAM returns the value of the specified parameter or, if you omit param-name, it
returns a space-separated list of all your parameters.
Considerations
If you supply both a parameter name and value, the specified parameter is set.
If you omit both the name and the value, all current parameters are cleared.
If you supply only a parameter name, the parameter is deleted.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-282
# P A R A M B u ilt-In V a ria b le
param-value
is the value assigned to param-name. It has a maximum length of 255
characters and must be no longer than one logical line. Specify param-value
as either character-sequence or "character-sequence".
If you do not use quotation marks, you cannot include any commas or spaces
as part of the parameter value.
If you do use quotation marks, all characters between the quotation marks are
included as part of the parameter value. To include quotation marks in the
parameter value, enter them twice (). (The enclosing quotes, and one of each
pair of doubled quotes, do not count against the 255-character size limit.)
Use two adjacent quotes to express an empty param-value.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-283
# P A U S E B uilt-In F u nctio n
Result
#PAUSE returns one of these:
Considerations
#PAUSE does not specify which process can access your terminal.
When you enter #PAUSE, the current TACL stops prompting for commands, thus
allowing any other processes to gain control of your terminal. TACL regains control
of your terminal, again displaying its prompt ( n> ), when it receives a process
deletion message from the specified process.
If the process you specify (process-name or cpu,pin) does not exist, or was not
created by the current TACL, #PAUSE waits until you press the BREAK key or
TACL receives a WAKE message.
If you do not specify a process, #PAUSE waits for the last process created by the
current TACL. If that process has already terminated, #PAUSE waits until you
press the BREAK key or TACL receives a WAKE message.
A process specification in #PAUSE establishes the identity of the default process;
see the #PROCESS Built-In Function on page 9-290 for information on the default
process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-284
#P M S E A R C H L IS T B u ilt-In V a ria b le
Result
#PMSEARCHLIST returns the current contents of the search list used for finding
programs and macro files.
Considerations
VOLUME $guest.alice
#SET #PMSEARCHLIST #DEFAULTS
VOLUME $new.jones
test
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-285
#P M S E A R C H L IS T B u ilt-In V a ria b le
VOLUME $guest.alice
#SET #PMSEARCHLIST [#DEFAULTS]
VOLUME $new.jones
test
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-286
#P M S G B u ilt-In V a ria b le
Result
#PMSG returns the current state of the PMSG flag: 0 if it is off, -1 if it is on.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-287
#P O P B uilt-In F u nctio n
Result
#POP returns nothing.
Considerations
If the top level is the only level, #POP deletes the variable (except for built-in
variables.
When it encounters an #UNFRAME, TACL performs an implicit #POP for every
#PUSH (or PUSH) that was done since the most recent #FRAME was issued.
TACL performs an implicit #POP on #IN when #INPUT /UNTIL EOF/ or #INPUTV
/UNTIL EOF/ is used.
An attempt to pop a variable that has not been pushed produces an Expecting an
existing variable message; an attempt to pop a built-in variable that has not been
pushed produces a Was not pushed message.
Do not try to #POP the root directory (:). If you try this, TACL returns "*ERROR*
Cannot push or pop the root segment's root." In addition, to avoid losing standard
functionality from your TACL environment, do not pop the directories supplied as
part of the TACL software product (such as UTILS).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-288
#P R E F IX B u ilt-In V a ria b le
Result
#PREFIX returns the current contents of the prompt prefix string.
Considerations
Example
1. This example illustrates the use of #PREFIX to output the current prompt prefix:
MINE 20> #OUTPUT [#PREFIX]
MINE
MINE 21>
2. This example shows the relationship between _PROMPTER, #PREFIX, and
#PROMPT:
63> [#DEF _prompter MACRO |BODY| == Define a macro
63> #SET #PREFIX Number
63> ]
64> #SET #PROMPT -1 == Enable the custom prompt
Number 65>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-289
# P R O C E S S B uilt-In F u nctio n
Result
#PROCESS returns the name of the default process or, if it has no name, its CPU,PIN;
if the process has been deleted, #PROCESS returns nothing.
Consideration
The #PROCESS built-in function returns a node name only if the process is running on
a remote node or if a remote node name is specified in the current defaults.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-290
#P R O C E S S E X IS T S B uilt-In F u nctio n
Result
#PROCESSEXISTS returns -1 (true) if the process exists; otherwise, it returns 0
(false).
Considerations
To obtain information about a process, use the #PROCESSINFO built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-291
#P R O C E S S F IL E S E C U R IT Y B u ilt-In V a ria b le
Result
#PROCESSFILESECURITY returns the current file-creation security, enclosed in
quotes, for this TACL process.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-292
#P R O C E S S F IL E S E C U R IT Y B u ilt-In V a ria b le
(Owner) Only the owner can access the file; the owner
must be logged on to the local system.
(Anyone) Any user can access the file; the user must be
logged on to the local system.
(User) Only the owner can access the file; the owner
can be logged on to the local system or a remote
system.
(Network) Any user can access the file; the user can be
logged on to the local system or a remote system.
When you log on, your security is set to the configuration you last specified
with the DEFAULTS utility.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-293
# P R O C E S S IN F O B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-294
# P R O C E S S IN F O B uilt-In F u nctio n
GUARANTEEDSWAPSPACE
returns the amount of swap space reserved for use by the process in bytes. It
returns nothing if the target system is running an operating system RVU earlier
than D40. An error message can be returned, indicating the option is invalid.
HOMETERM
returns the name of the home terminal.
INITPRI
is the initial priority of a process when it begins execution or as changed by a
call to the PRIORITY or PROCESS_SETINFO_ operating system procedures
or related TACL commands and built-in functions such as ALTPRI,
#ALTERPRIORITY, and #PROCESS. (The current priority might be less
because of the sliding priority algorithm used by the operating system.)
IPUASSOCIATION
returns the IPU affinity attributes for the process indicating whether or not the
process is bound to an IPU and whether or not it is bindable. This attribute is
undefined if the system is running an operating system version earlier than
H06.27 or J06.16.
IPUNUMBER
returns the number of the IPU on which the process last ran.
LOGONNAME
returns the user name (group name,user name), user ID (group
number,user number), or user alias specified in the current LOGON
command. For pre-D30 software RVUs, this option returns nothing.
LIBRARY
returns the name of the library file used by the process. If the process has no
associated library file, this option returns nothing.
LICENSES
equals 1 if the object file was licensed at process creation time; otherwise, it
equals 0.
LOGONSTATE
equals 1 if the process is logged on; otherwise, it equals 0.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-295
# P R O C E S S IN F O B uilt-In F u nctio n
MAXMAINSTACKSIZE
returns the maximum size, in bytes, to which the main stack can grow. It
returns nothing if the target system is running an operating system RVU earlier
than D40. An error message can be returned, indicating the option is invalid.
MAXNATIVEHEAPSIZE
returns the maximum size, in bytes, to which the native heap area can grow. It
returns nothing if the target system is running an operating system RVU earlier
than D40. An error message can be returned, indicating the option is invalid.
MOM
is the process identifier of the MOM of the process. If the process is named,
#PROCESSINFO returns the name; otherwise, CPU and PIN are returned.
The MOM process is always qualified with a node name. If the process has no
existing parent, nothing is returned.
When a process is part of a process pair, the MOM of the process is the
other member of the pair.
When a process is unnamed, the MOM of the process is usually the
process that created it.
For a named single process, nothing is returned.
More information about the MOM process can be found in the Guardian
Procedure Calls Reference Manual and the Guardian Programmers Guide.
NATIVE
returns 1 if the process is a native process (that is, runs on a RISC-based
operating system without interpretation or translation), returns 0 if the process
is a non-native process. For pre-D40 software RVUs, this option returns
nothing.
OSSARGUMENTS
returns the first 80 bytes of the arguments of the command that created the
OSS process. The arguments that are returned may or may not be separated
by spaces. If the process is not an OSS process, this option returns nothing.
For pre-D30 software RVUs, this option returns nothing.
OSSPATHNAME
returns a fully qualified OSS program pathname if the process is an OSS
process. The maximum length of an OSS program pathname (in the OSS file
name format) is 1024 bytes. If the process is not an OSS process or if the OSS
program is running on a remote node, this option returns nothing. For pre-D30
software RVUs, this option returns nothing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-296
# P R O C E S S IN F O B uilt-In F u nctio n
OSSPID
returns an OSS process ID if the process is an OSS process. An OSS process
ID is an integer value. If the process is not an OSS process, this option returns
nothing. For software RVUs preceding the D30 RVU, this option returns
nothing.
PAID
returns the process accessor ID as (group-num,user-num).
PFR
(an abbreviation for privileged-fault-ready) returns a three-digit number. If there
is a 1 in the leftmost digit position, it indicates that the process is privileged; a 1
in the second position indicates that the process is waiting because of a page
fault; a 1 in the third position indicates that the process is on the ready list. The
digits are zero otherwise.
PIN
returns the process identification number.
PRI
returns the priority of the process.
PRIMARY
equals 1 if the process is the primary of a named process pair; otherwise, it
equals 0.
PROCESSCREATIONTIME
returns the Julian timestamp that identifies the time when the process was
created. This attribute is supported on H and J series systems.
PROCESSDESCRIPTOR
is a process descriptor that includes the node name and sequence number.
PROCESSFILESECURITY
is the default file security for files created by the specified process. Four
uppercase characters are returned, enclosed in double quotes.
PROCESSID
returns the process name. If the process has no name, PROCESSID returns
the CPU and PIN of the process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-297
# P R O C E S S IN F O B uilt-In F u nctio n
PROCESSSTATE
returns a line of twelve space-separated values: eleven flags and a numeric
value. The flags are encoded as -1 (true) or 0 (false), and represent this
information:
Flag
Meaning
Privileged process
System process
Reserved
Reserved
10
11
State
Unallocated
Starting
Runnable
Suspended
DEBUG MAB
DEBUG breakpoint
DEBUG trap
DEBUG request
INSPECT MAB
INSPECT breakpoint
10
INSPECT trap
11
INSPECT request
12
SAVEABEND
13
Terminating
14
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-298
# P R O C E S S IN F O B uilt-In F u nctio n
PROCESSTIME
returns the central processing unit time in microseconds that the process has
consumed (as opposed to elapsed run time). If the process is remote and is
running on a NonStop 1+ system, it returns 0.
PROCESSTYPE
returns an unsigned integer value that indicates the process type. If the
process is a Guardian process it returns 0. If the process is an OSS process, it
returns 1.
PROGRAMDATAMODEL
returns 1 if the target process is a 64-bit process; otherwise 0 is returned. 0 is
returned if the target system is running an operating system version earlier
than H06.24 or J06.13.
PROGRAMFILE
returns the program file name. If the process is a system process, is remote,
and is running on a NonStop 1+ system, it returns nothing.
If the process is an OSS process, it returns the generic Guardian ZYQ-file
name.
If the program file name for a process cannot be retrieved, *ERROR* Path
to program file name down is written to the output file, and the TACL
program stops. This situation can occur if the processor for the disk process
controlling the disk where the program file resides fails, making the process file
name unavailable.
QUALINFOAVAIL
equals 1 if the process has called the PROCESS_SETINFO_ operating system
procedure to declare that it supports qualifier name searches through the
FILENAME_FIND_ operating system procedures; otherwise, it equals 0.
REMOTECREATOR
equals 1 if the processs creator is remote; otherwise, it equals 0.
RESULT
returns an indication of the success of the #PROCESSINFO call, as follows:
Value
Meaning
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-299
Value
Meaning
99
# P R O C E S S IN F O B uilt-In F u nctio n
SRLFILES
returns a list of shared run-time library (SRL) file names used by the process. A
maximum of 32 SRLs can be attached to a process. If the process has no
associated SRLs, this option returns nothing. If the operating system RVU
precedes the D40 RVU, this option returns nothing.
SRLNAMES
returns a list of SRL names used by the process. A maximum of 32 SRLs can
be attached to a process. If the process has no associated SRLs, this option
returns nothing. If the operating system RVU precedes the D40 RVU, this
option returns nothing.
SRLNUMFILES
returns the number of SRL files used by the process. A maximum of 32 SRLs
can be attached to a process. If the process has no associated SRLs, this
option returns 0. This value is the number of SRL files returned from the
system procedure PROCESS_GETINFOLIST_. Some of the SRL file entries
can be empty. If the operating system RVU precedes the D40 RVU, this option
returns nothing.
SRLNUMNAMES
returns the number of SRL names used by the process. A maximum of 32
SRLs can be attached to a process. If the process has no associated SRLs,
this option returns 0. This value is the number of SRL files returned from the
system procedure PROCESS_GETINFOLIST_. Some of the SRL file entries
can be empty. If the operating system RVU precedes the D40 RVU, this option
returns nothing.
SUBDEVICE
is a subdevice type.
SWAP
returns the name of the file used for storing the virtual data of a process. This
name is specified in the SWAP swap-file option of the RUN command or
with the SET SWAP [ $volume-name ] command. If nothing is specified
with either (or both) the RUN command SWAP option or SET SWAP
command, a dummy file name, "$volume.#0", is returned. In this case,
#volume is the name of the physical volume that the operating system has
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-300
# P R O C E S S IN F O B uilt-In F u nctio n
selected for storing the file. For pre-D40 software RVUs, this option returns
nothing. For more information on the swap facility, see the Kernel-Managed
Swap Facility (KMSF) Manual.
SYSTEM
returns the name of the system.
UPB
returns a single character (U, P, or B) that indicates whether the process is
unnamed or, if named, is the primary or backup of the process pair.
WAITSTATE
returns a space-separated list of eight flags encoded as -1 (true) and 0 (false),
as follows:
Flag
INTR (interrupt)
WT
returns a three-digit octal value, as follows:
Value
Meaning
%000
%001
%002
%004
%005
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-301
# P R O C E S S IN F O B uilt-In F u nctio n
search-option
is a search option for use with one or more of the preceding options, as follows:
SEARCH criterion
specifies a criterion that the process must match; if you specify multiple
SEARCH options, the process must match all the criteria. criterion can be
any of these:
CAID [ user ]
specifies that the creator accessor ID must match the specified user. If you
omit the user identification, #PROCESSINFO searches for a process with
the same CAID as the TACL process.
GMOMJOBID [ job-id ]
states that the job-ancestor.job-id must match the specified jobid. If you omit the job identification, #PROCESSINFO searches for a
process with the same GMOMJOBID as the TACL process.
HOMETERM [ $terminal-name ]
specifies that the home terminal name must match the specified
$terminal-name. If you omit the terminal identification,
#PROCESSINFO searches for a process with the same CAID as the TACL
process.
HOMETERM [ $terminal-name
specifies that the home terminal name must match the specified
$terminal-name. If you omit the terminal identification,
#PROCESSINFO searches for a process with the same HOMETERM as
the TACL process.
MINPRI num
searches for a process whose priority is greater than or equal to the
specified number. (MINPRI can be used in combination with SEARCH PRI
to search for a process whose priority lies in a specified range.)
PAID [ user ]
specifies that the process accessor ID must match the specified user. If
you omit the user identification, #PROCESSINFO searches for a process
with the same PAID as the TACL process.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-302
# P R O C E S S IN F O B uilt-In F u nctio n
PRI [ num ]
specifies that the priority must be less than or equal to the specified num. If
you omit the priority specification, #PROCESSINFO searches for a
process with a priority less than that of the TACL process.
PROCESSID [[\node-name.]{$process-name | cpu,pin } ]
specifies that the process identification must match the specified
$process-name or cpu,pin (if you omit both, the process identification
must match the TACL process ID).
PROGRAMFILE [[\node-name.] file-name-template ]
specifies that the name of the program file must match the specified filename-template. You can include the template characters:
*
Result
#PROCESSINFO returns a space-separated list of the information requested.
Considerations
The information is returned in the order in which you specify the options.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-303
# P R O C E S S IN F O B uilt-In F u nctio n
The process ID that follows the slashes determines where TACL searches for a
process:
TACL uses a starting CPU,PIN if specified; otherwise, TACL uses the CPU and
PIN of its own primary process. TACL starts searching at that CPU and PIN,
then searches higher PINs in the same CPU. If no matching process is found,
TACL searches higher-numbered CPUs for a matching process.
If you specify nothing, TACL starts searching from the CPU,PIN of its own
primary process.
The starting CPU and PIN affect whether #PROCESSINFO returns information
about a primary or backup process. TACL returns information about the first
matching process that occurs at or beyond the starting point of the search.
If no process can be found that matches the specifications (RESULT returns a
value other than 0 or 1) no other results are returned. Therefore, you should use
the RESULT option first.
If you include one or more SEARCH options, TACL uses the CPU,PIN as the
beginning search point.
If you use SEARCH more than once, the process must meet all the specified
criteria.
To obtain information about a process on a node other than the current default
system, specify the remote node by using a SEARCH SYSTEM or SEARCH
PROCESSID command (see Examples on page 9-306).
You can specify the search system redundantly, using both SEARCH and a system
specification following the option set, but if you give conflicting system
specifications, TACL returns RESULT = 99 (inconsistent parameters).
Because the home terminal and process-ancestor job ID of a process can reside
on different systems from the process itself, specifying a system by either of:
#PROCESSINFO /SEARCH HOMETERM \system.$terminal-name/
#PROCESSINFO /SEARCH GMOMJOBID \system.$process.job-id/
has no effect on the search system. Note that it is essential to specify a system in
SEARCH HOMETERM or SEARCH GMOMJOBID if the home terminal or processancestor job ID is on a system other than the current default system.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-304
# P R O C E S S IN F O B uilt-In F u nctio n
If you do not specify a system in the SEARCH PROGRAMFILE option, TACL does
not assume that you are referring to the current default system; instead, it assumes
that the program file resides on the search system.
The recommended way to get information about a given process is as follows:
#PROCESSINFO /RESULT, ... ,SEARCH PROCESSID [p]/ 0,0
(assuming the variable P contains the process ID). This search method says
search for process [p], starting at CPU,PIN 0,0. Another way of doing this:
#PROCESSINFO /RESULT, ... / [p]
This second method says start searching for a process at the CPU,PIN of the
primary of [p], meaning TACL finds [p] itself; but if [p] expands to a CPU,PIN
instead of a process name, and if the process at that location has terminated,
#PROCESSINFO reports on the process at the next higher CPU,PIN.
Use care in getting several items of information from one call to #PROCESSINFO,
especially if assigning the results to variables with #SETMANY, as some options
may return nothing:
EXTSWAP is empty if the process does not have an extended swap file.
GMOMJOBID is empty if the process has no GMOM.
LIBRARY is empty if the process has no library file.
MOM is empty if the process is an orphan.
SYSTEM is empty if the process is local.
# P R O C E S S IN F O B uilt-In F u nctio n
Examples
These examples show three different ways to list the CPU number of process $SPLS
on system \TEST. $SPLS has CPU and PIN numbers 0,33.
15> #PROCESSINFO /SEARCH SYSTEM \TEST, CPU/ $SPLS
#PROCESSINFO expanded to:
0
16> #PROCESSINFO /CPU/ \TEST.$SPLS
#PROCESSINFO expanded to:
0
17> #PROCESSINFO /CPU/ \TEST.0,33
#PROCESSINFO expanded to:
0
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-306
# P R O C E S S L A U N C H B uilt-In F u nctio n
MAXMAINSTACKSIZE, allowing the user to specify the maximum main stack size
MAXNATIVEHEAPSIZE, allowing the user to specify the maximum size of the
native heap area
GUARANTEEDSWAPSPACE, allowing the user to specify the amount of space
that the process reserves with the Kernel-Managed Swap Facility for swapping.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-307
# P R O C E S S L A U N C H B uilt-In F u nctio n
param-set
is a program parameter or a series of parameters sent to the new process in the
startup message. Leading and trailing spaces are deleted.
Result
See the #NEWPROCESS Built-In Function on page 9-265.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-308
# P R O C E S S O R S T A T U S B uilt-In F u nctio n
Result
#PROCESSORSTATUS returns a space-separated list of 17 numbers. The first
number indicates the highest processor number present in the system, plus one.
The remaining 16 numbers are the status of each of the 16 possible CPUs, starting
with CPU 0. For each running CPU, the status is -1. For each halted or absent CPU,
the status is 0.
If the specified system is unknown or unavailable, TACL returns this message:
Expecting an available system Or End
Example
This example illustrates the result of a #PROCESSORSTATUS call:
15> #OUTPUT [#PROCESSORSTATUS]
16 -1 -1 -1 -1 -1 -1 0 0 0 0 0 0 0 0 0 0
The local system has 16 configured processors and six active processors, running as
CPUs 0 through 5.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-309
# P R O C E S S O R T Y P E B uilt-In F u nctio n
Results
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-310
# P R O C E S S O R T Y P E B uilt-In F u nctio n
Meaning
-1
-2
-3
You specified the BOTH option, and the system does not support the
option.
If you specify the NAME option and an error occurs, TACL does not
return any text.
Example
If you call #PROCESSORTYPE for CPU 0, and CPU 0 is a NonStop EXT25 processor,
TACL returns the following:
29> #PROCESSORTYPE 0
#PROCESSORTYPE 0 expanded to:
2
30>
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-311
#P R O M P T B u ilt-In V a ria b le
Result
#PROMPT returns -1 if the prompt flag is on, 0 if it is off.
Considerations
When it is on, the prompt flag causes TACL to try to invoke a macro or routine
called _PROMPTER just before issuing a prompt. Your _PROMPTER macro
can add text to the standard TACL prompt by using the #PREFIX built-in
variable.
If you press BREAK or an error occurs during your prompt macro, #PROMPT
is automatically set to zero.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-312
# P U R G E B uilt-In F u nctio n
Result
#PURGE returns zero if it removes the file successfully; otherwise, it returns the filesystem error indicating the reason for the failure.
Considerations
When you use #PURGE to remove a disk file, the file entry is removed from the file
directory in that volume, and any space previously allocated to that file is made
available. Data in the file is not physically removed from the disk unless you
specified the CLEARONPURGE option when you created the file: removed files
are then overwritten with spaces. For information about the
CLEARONPURGE option, see the FUP CREATE command description in the File
Utility Program (FUP) Reference Manual. You can purge a file only if it is not
currently open. You must have purge access to the file. See the description of the
FUP SECURE command in the File Utility Program (FUP) Reference Manual for
information about file-access restrictions.
If you try to use the PURGE command to remove a file that is being audited by the
TMF subsystem, the attempt fails, and file-system error 12 (file in use) is returned if
there are pending transaction-mode records or file locks. A PURGE attempt of this
kind is blocked regardless of whether the processes that opened the file still exist.
Example
This example illustrates the use of #PURGE with status reporting:
#PUSH old^file
#SET old^file $DATA.FILES.TEMP1
[#IF [#PURGE [old^file]] |THEN| #OUTPUT **Purge failed**]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-313
#P U S H B uilt-In F u nctio n
Result
#PUSH returns nothing.
Considerations
The PUSH command is an alias for the #PUSH built-in function and can be used
interchangeably with it.
For variables, #PUSH creates an empty top level of type TEXT.
For built-in variables, #PUSH creates a new top-level definition, copying the old
top-level definition to the new one (top-level and second-level definitions are now
the same).
If the variable does not exist, PUSH registers the name of the variable, but does
not allocate space until you use #SET or a similar command or built-in function to
actually place data into the variable. As a result, you must perform a SET
VARIABLE or related operation prior to using the variable in an #IF call or other
command or function that tests the value of the variable.
Do not try to #PUSH the root directory (:). If you try this, TACL returns "*ERROR*
Cannot push or pop the root segment's root."
To avoid losing standard functionality from your TACL environment, do not #PUSH
directories supplied as part of the TACL product (such as UTILS).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-314
#R A IS E B uilt-In F u nctio n
Result
#RAISE returns nothing.
Consideration
All routines up to and including the one having the exception filter are eliminated, and
the routine that issued #FILTER is reinvoked. You can use #EXCEPTION to deter mine
why the routine was reinvoked. (See the discussion of exception handling in the TACL
Programming Guide and the example fro the #FILTER Built-In Function on
page 9-178.)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-315
# R E N A M E B uilt-In F u nctio n
Result
#RENAME returns zero if it renames the file successfully otherwise, it returns the filesystem error that indicates the reason for the failure. If, however, the error is caused by
a missing old-file-name, or if that file does not exist, TACL displays an
expecting the name of an existing file message.
Considerations
The new file name must be on the same volume as the old file name.
You can rename a file only if it is not open with exclusive access and you either
have purge access to the file or are logged on as a super-group user.
You can use the RENAME command to change the subvolume name of a file, but
not its volume name. Disk files that are renamed stay on the same disk volume.
To change the volume where a file resides, copy the file to a new volume with the
FUP DUP command, then delete the original file. For details, see the File Utility
Program (FUP) Reference Manual.
If you try to rename a file being audited by the TMF subsystem, the attempt fails
and file-system error 80 (operation invalid) is returned.
Both format 1 and format 2 files can be renamed.
Example
This code renames a file and checks whether the rename was performed without
errors:
[#IF [#RENAME oldn newn] |THEN|
#OUTPUT Rename Error
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-316
# R E P LY B uilt-In F u nctio n
Result
#REPLY returns nothing.
Considerations
The #REPLY function is used when TACL functions as a server. For additional
information, see the #SERVER Built-In Function on page 9-339 built-in function.
If there is already text in the reply, through previous calls to #REPLY or #REPLYV
(or calls to #OUTPUT or #OUTPUTV if the OUT file for TACL is also $RECEIVE), a
space precedes the added text in the accumulated reply.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-317
#R E P LY P R E F IX B u ilt-In V a ria b le
Result
#REPLYPREFIX returns the current value of the reply prefix.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-318
# R E P L Y V B uilt-In F u nctio n
Result
#REPLYV returns nothing.
Considerations
The #REPLYV function is used when TACL functions as a server. For additional
information, see #SERVER Built-In Function on page 9-339.
If there is already text in the reply, through previous calls to #REPLY or #REPLYV
(or calls to #OUTPUT or #OUTPUTV if the TACL OUT file is also $RECEIVE), a
space precedes the added text in the accumulated reply.
The form
#REPLYV struct
is not equivalent to
#REPLY [ struct]
The latter appends the external representation of the STRUCT, rather than its actual
binary data, to the reply.
Example
This example shows the use of both quoted text and a variable name in constructing a
reply:
#PUSH termname
#SET termname [#MYTERM]
#REPLYV "My terminal is " '+' termname '+' " at this time."
Assuming that the home terminal is named $WEIRD at the time the #SET function is
invoked, the following is included in the reply:
My terminal is $WEIRD at this time.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-319
# R E Q U E S T E R B uilt-In F u nctio n
# R E Q U E S T E R B uilt-In F u nctio n
CLOSE variable-level
closes the file and deletes the requester associated with variable-level. If it is
a write requester, use #WAIT on write-var to ensure that all data in the write
variable has been written to the file before you delete the requester.
variable-level
is any one of the variable levels used when #REQUESTER was invoked to
open a file. For example, if you start a requester with the READ option, you
can specify the same error-var, read-var, or prompt-var with the
CLOSE option. A given variable level can be associated with only one
requester or server at any time. The variable level must not be a DIRECTORY,
STRUCT, or a STRUCT item.
READ file-name error-var read-var prompt-var
creates a read requester and opens file-name for reading. For each line
appended to prompt-var, the requester reads a record from file-name and
appends it to read-var. If file-name is a terminal or a process, appending a
line to prompt-var causes the value of the variable to be transmitted as a
prompt. If you use the WAIT option, TACL begins executing subsequent code, but
if it encounters #APPEND(V) or #EXTRACT(V) that refers to a requester variable,
it waits until the I/O operation is finished.
If you do not use WAIT, TACL continues execution. To avoid reading incorrect data,
use the #WAIT function. Use #APPEND(V) prompt-var and #EXTRACT(V)
read-var instead of the #SET(V) built-in functions. If an error occurs, errorvar is set to the error number and further I/O operations on the requester stop until
you clear error-var by setting it to a null value.
file-name
is the name of the file to be read. If the file does not exist, an error occurs. Both
format 1 and format 2 files (unstructured, file code 0 format 2 files only) can be
read.
error-var
is the name of a variable level to hold error codes.
read-var
is the name of a variable level to hold the data read.
prompt-var
is the name of a variable level to hold one prompt for each line to be read.
Note. The variable level cannot be a DIRECTORY, STRUCT, or STRUCT item.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-321
# R E Q U E S T E R B uilt-In F u nctio n
Result
#REQUESTER returns zero if it is successful; otherwise, it returns a file-system error
indicating the reason for failure. A TACL error causes an exception rather than
returning an error.
Considerations
The #REQUESTER function does not create a separate requester function. It runs
as part of the TACL process. You read and write data through the use of
associated variables (read-var, prompt-var, and write-var).
The first call to #REQUESTER opens the file and associates the variables with the
file, but does not perform any input or output to the file.
To initiate input for a READ operation, place data in prompt-var (in this
example, defined as pvar):
#APPEND pvar *read next*
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-322
# R E Q U E S T E R B uilt-In F u nctio n
This action triggers a read operation. If you are reading from a file, TACL ignores
the contents of prompt-var. If you are reading from a process or device, TACL
sends the contents of prompt-var to the process or device as part of a
WRITEREAD operation.
If you specify a WRITE requester for a nonexistent disk file, TACL creates an editformat file; if you specify a READ requester for a nonexistent file, a file-system
error occurs.
If #REQUESTER is unsuccessful in creating a requester, such as in the case
above, it returns the file-system error in its result. If it is successful, any future
errors (such as end-of-file in a read requester) are returned in error-var.
All I/O for no-wait requesters takes place while normal TACL processing continues.
I/O automatically occurs when information becomes available in the variables and
files specified. To synchronize I/O, use the #WAIT built-in function.
A requester, waited or no-wait, that does I/O on a disk file requires that TACL
internally allocate one of its block buffers. Because these block buffers are large
and must be allocated from the first 64K bytes of the TACL address space, there
are only four of them. Each block buffer is 1024 bytes. The #IN and #OUT built-in
functions also require these buffers. A block buffer is passed to the SIO procedure
to help perform read and write operations to the file. SIO uses the block buffers
whenever necessary.
For structured files, block buffers can be used to improve the efficiency of read
operations. For edit-format files, block buffers are required by SIO to perform write
padding of records. For other types of files, block buffers can be used for record
blocking and unblocking.
If you specify a waited requester with a record length greater than 1024 bytes,
TACL allocates one of its block buffers. SIO automatically turns off block buffering
because the record length is greater than the block buffer length.
The only way you can use large buffers is by using waited requesters; a waited
requester still counts against the block buffer limit.
The maximum record lengths are as follows:
Edit-format files
239 bytes
No-waited requesters
239 bytes
1024 bytes
5000 bytes
For non-edit disk files, trailing blanks at the end of a STRUCT (for example,
FILLER bytes or trailing blanks in the last STRUCT data item) are not trimmed
from the output record before being written to the file using the #APPENDV built- in
function. For edit-format files, SIO automatically trims trailing blanks from the
output record before it is written to the file.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-323
# R E Q U E S T E R B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-324
# R E S E T B uilt-In F u nctio n
Result
#RESET returns nothing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-325
# R E S T B uilt-In F u nctio n
Result
#REST returns the remainder of the arguments of the current routine.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-326
# R E S U LT B uilt-In F u nctio n
Result
#RESULT returns nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-327
#R E T U R N B uilt-In F u nctio n
Result
#RETURN returns nothing.
Considerations
TACL immediately exits from the current routine as though there were no more
code after #RETURN.
#RETURN does not reset #FRAMEs. If you use #RETURN, be sure to
#UNFRAME any #FRAME within your routine or call #RESET FRAMES to invoke
#UNFRAME for all frames with frame numbers higher than they were when the
routine was entered.
To provide alternative exits, you can include multiple, conditional #RETURN
commands in a single routine.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-328
#R O U T E P M S G B u ilt-In V a ria b le
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-329
#R O U T E P M S G B u ilt-In V a ria b le
These tables define the outcome of setting the #PMSG and #ROUTEPMSG built-in
variables. These outcomes are possible:
Yes
No
N.A.
This table defines the type of messages output by the #PMSG setting:
#PMSG
System
Normal
Process
Abnormal
Process
-1 (on)
Yes
Yes
Yes
0 (off)
Yes
No
Yes
This table defines how the #ROUTEPMSG setting affects message output if
#PMSG is on:
#ROUTEPMSG
System
Normal
Process
Abnormal
Process
ALL
No
No
No
SYSTEM
No
Yes
Yes
NORMAL
Yes
No
Yes
ABNORMAL
Yes
Yes
No
SYSTEM NORMAL
No
No
Yes
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-330
#R O U T E P M S G B u ilt-In V a ria b le
#ROUTEPMSG
System
Normal
Process
Abnormal
Process
SYSTEM ABNORMAL
No
Yes
No
NORMAL ABNORMAL
Yes
No
No
STANDARD
Yes
Yes
Yes
This table defines how the #ROUTEPMSG setting affects message output if
#PMSG is off:
#ROUTEPMSG
System
Normal
Process
Abnormal
Process
ALL
No
N.A.
No
SYSTEM
No
N.A.
Yes
NORMAL
Yes
N.A.
Yes
ABNORMAL
Yes
N.A.
No
SYSTEM NORMAL
No
N.A.
Yes
SYSTEM ABNORMAL
No
N.A.
No
NORMAL ABNORMAL
Yes
N.A.
No
STANDARD
Yes
N.A.
Yes
Example
To suppress all messages, enter:
> #SET #ROUTEPMSG ALL
> #ROUTEPMSG
#ROUTEPMSG returns the current state of the #ROUTEPMSG built-in variable, which
could be one of:
ALL
SYSTEM
NORMAL
ABNORMAL
SYSTEM NORMAL
SYSTEM ABNORMAL
NORMAL ABNORMAL
STANDARD
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-331
#R O U T IN E N A M E B uilt-In F u nctio n
Result
#ROUTINENAME returns the fully qualified name of the variable level holding the
currently active routine. If invoked from a routine stored in a ?TACL ROUTINE file, it
returns the name of the variable TACL created to hold a copy of the routine while it is
active (it cannot obtain the name of the original file).
Considerations
Examples
Given this library,
?SECTION rumph ROUTINE
#OUTPUT Percents show name as %0%.
#OUTPUT Routinename shows name as [#routinename].
?SECTION grumph MACRO
#OUTPUT Percents show name as %0%.
#OUTPUT Routinename shows name as [#routinename].
invoking the routine and the macro gives these results:
36> RUMPH
Percents show name as %0%.
Routinename shows name as :RUMPH.1.
37> GRUMPH
Percents show name as :GRUMPH.1.
#OUTPUT Routinename shows name as [#routinename]
^
*ERROR* No routine has been called
You can also use #ROUTINENAME to invoke a variable that will reside in the same
directory as the routine itself, without stating the directory name explicitly:
[#VARIABLEINFO /DIRECTORY/ [#ROUTINENAME]]:elf elf-args
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-332
# S E G M E N T B uilt-In F u nctio n
Result
Without the USED option, #SEGMENT returns the segment file name.
If you include the USED option, #SEGMENT returns an estimate of the number of
bytes currently used in your segment.
Consideration
To obtain information about a segment file, use the #SEGMENTINFO built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-333
# S E G M E N T C O N V E R T B uilt-In F u nctio n
Result
#SEGMENTCONVERT returns nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-334
# S E G M E N T C O N V E R T B uilt-In F u nctio n
Whenever a RVU of TACL after C10 tries to attach a C00/C10 segment file, it
automatically creates a temporary segment file in format version C20 or later,
copies the older file to it, and attaches the temporary file instead. This typically
happens every time you log on. Converting the older file to the newer format
eliminates this action, as well as the disk space requirements of the temporary
file.
If you create a variable with a C20 or later RVU of TACL, and the variable
contains a y-dieresis character (in the international character set), and you
write the variable to a C00/C10 segment file, it can corrupt the file. Converting
the file to newer format eliminates that risk.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-335
# S E G M E N T IN F O B uilt-In F u nctio n
# S E G M E N T IN F O B uilt-In F u nctio n
For execution
To point to other segments
USED
returns the number of bytes in use in the segment.
segment-id
is the segment ID at which to begin searching. If you omit it, segment zero is
assumed.
Result
#SEGMENTINFO returns a space-separated list of the specified information in the
order it was requested.
Consideration
To obtain the name of your default segment file, use the #SEGMENT built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-337
# S E G M E N T V E R S IO N B uilt-In F u nctio n
Result
#SEGMENTVERSION returns one of these characters:
A
If the specified file does not exist, cannot be opened, cannot be read, or is not a TACL
segment file (file code 440), TACL issues an appropriate error message.
Consideration
To convert a segment to the other format, use the #SEGMENTCONVERT built-in
function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-338
#S E R V E R B uilt-In F u nctio n
#S E R V E R B uilt-In F u nctio n
KILL
specifies that the indicated server is to be deleted. You must specify a servername for this option. If a server is deleted, any processes that still have the
server open receive file-system error 66 (device downed) on subsequent I/O
operations to the named server.
name
is the access name of your TACL process. This argument is optional unless you
specify the KILL option. The name consists of your TACL process name followed
by a period, a number sign, a letter, and zero to six alphanumeric characters
($D127.#K39, for example); if you want, that can be followed by another period, a
letter, and zero to seven alphanumeric characters ($D127.#K39.ACM48, for
example). If you specify a create option and do not specify a name, TACL creates
one, of the form:
$your-tacl-name.#Snn
where nn is the next available server number.
Result
If you supply one or more create options, #SERVER returns a name for your TACL
process.
If you specify the KILL option, #SERVER returns nothing.
Considerations
When a process writes to your TACL process, the line is appended to the end of
the OUT variable of the server. When a process prompts for input, the prompt is
stored in your PROMPT variable, destroying all previous contents. When a process
reads a line from your TACL process, TACL removes the first line of the IN variable
and passes it to the process. If the IN variable is empty, the requesting process
waits until you put more data into the IN variable.
A TACL process can have a maximum of 100 simultaneous openers, but only one
process can read from it at a time. If one process has requested data from the IN
variable and a second process tries to retrieve data from the IN variable, the
second process receives a file-system error 28 (attempt to open a disk file or
$RECEIVE with maximum number of concurrent operations greater than one).
You can use the create options-IN, OUT, and PROMPT-in combination, but KILL
must be used alone.
There is a potential deadlock situation when using #SERVER to control DEBUG
and INSPECT for a process started by the same TACL. The deadlock occurs
because TACL waits for the program to read its startup messages, which it cannot
do because it is waiting for an R command from DEBUG or INSPECT, which in
turn is waiting for input from a TACL variable. To avoid this situation, before issuing
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-340
#S E R V E R B uilt-In F u nctio n
Examples
To create an access name for your TACL process:
#PUSH access_name in_var out_var prompt_var
#SET access_name [#SERVER /IN in_var, PROMPT prompt_var, &
OUT out_var/]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-341
#S E R V E R B uilt-In F u nctio n
Table 9-12 lists commands that a TACL process using #REQUESTER and a TACL
process using #SERVER can use to communicate with each other. The decision to use
one-way or two-way communication depends entirely upon how the server responds to
requests.
Table 9-12. Communicating with a TACL Requester
Type of
Communication
#Requester
#Server
Two-way
communication
(WRITEREAD
operation)
Invokes #APPENDV
prompt^var var (initiates a
WRITEREAD operation)
Invokes #EXTRACTV
prompt^var var (performs a
READUPDATE operation)
Invokes #EXTRACTV
read^var data (retrieves the
response)
One-way
communication
(WRITE operation)
Invokes #APPENDV
write^var var (initiates a
WRITE operation)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-342
#S E T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-343
#S E T B uilt-In F u nctio n
MACRO
specifies that text is a TACL macro.
ROUTINE
specifies that text is a TACL routine.
TEXT
specifies that text is simply text; that is, it has no special meaning to
TACL.
variable-level
is the name of the existing variable level to be set.
text
is the text to be put into the specified variable level.
built-in-variable
is the name of a built-in variable.
built-in-text
is the new value for the built-in variable.
Result
#SET returns nothing.
Considerations
#SET replaces the current contents of variable-level with the specified text or,
if you indicate a file with the IN option, with the contents of the specified file.
You cannot use a text entry with the IN option, nor can you use the IN option with a
built-in variable.
The IN option reads data in the PLAIN mode. The TACL process does not interpret
metacharacters as metacharacters; nor does it expand variables.
Unless you specify a TYPE option, the type of the variable level remains
unchanged. You cannot use the TYPE option with a built-in variable.
When setting a built-in variable, the format of text must be appropriate for that
particular variable. See the description of the built-in variable in question.
You cannot insert leading or trailing spaces into a variable level with #SET.
To copy a string to an existing variable level, use the #SETV built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-344
#S E T B uilt-In F u nctio n
Examples
1. This example sets a built-in variable:
32> #SET #WIDTH 132
2. The next example sets a user-defined variable level:
33> #SET vara This is it
3. This example illustrates the use of level specifications to put different information
into different levels of the variable var:
34> #PUSH var
35> #PUSH var
36> #SET / TYPE TEXT / var.1 TIME
37> [#SET / TYPE MACRO / var.2
37> #OUTPUT The first argument is %1%
37> ]
38> var.1
July 12, 1990 15:55:51
39> var.2 hardest
The first argument is hardest
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-345
# S E T B Y T E S B uilt-In F u nctio n
Result
#SETBYTES returns nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-346
# S E T C O N F IG U R A T IO N B uilt-In F u nctio n
option
must be one or more of these:
AUTOLOGOFFDELAY delay-value
specifies the maximum number of minutes TACL is to wait at a prompt. If the
specified time is exceeded, TACL automatically logs off, releases the default
segment, and (if LOGOFFSCREENCLEAR is specified) clears the terminal
screen. The default is -1 (disabled).
A TACL process issues a modem disconnect at autologoff.
BLINDLOGON { OFF | ON }
specifies the LOGON command, whether in the logged-off state or the loggedon state, prohibits the use of the comma, requiring the password to be entered
at its own prompt while echoing is disabled. The default is OFF.
CMONREQUIRED [ OFF | ON }
specifies that all operations requiring approval by $CMON be denied if $CMON is not
available or is running too slowly. Approval of $CMON is not required if the TACL is
already logged on as the super ID. The default is OFF.
Caution. If yo u are a u tho rize d to ch a n ge C M O N R E Q U IR E D a n d in ten d to se t it to O N , yo u
m u st ke e p a n u n m o d ifie d co p y o f T A C L for syste m o p e ra tio n u se . O th erw ise , yo u ca n no t lo g
o n if $ C M O N is n o t ru n n ing o r is ru nn in g to o slo w ly. If th e m o dified T A C L is in
$ S Y S T E M .S Y S n n , yo u ca n no t e ve n sta rt th e syste m .
CMONTIMEOUT timeout-value
specifies the number of seconds that TACL is to wait for any $CMON
operation. The default timeout-value is 30.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-347
# S E T C O N F IG U R A T IO N B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-348
# S E T C O N F IG U R A T IO N B uilt-In F u nctio n
REQUESTCMONUSERCONFIG [ OFF | ON ]
if set to ON, then, after every LOGON command or #CHANGEUSER built-in
function is executed, the TACL process sends a request to the $CMON
process for the configuration parameters in effect for this current TACL user.
if set to OFF, then the configuration parameters in effect are always the TACL
process default parameters, parameters obtained when a LOGOFF command
has been executed and is followed (at some point) by a LOGON command, or
parameters obtained when a noninteractive TACL process is started.
This option is initially set to OFF.
This option is meaningful only if the $CMON process has been coded to return
the configuration information. Otherwise, the additional request is ignored. Use
of this option allows $CMON to control (and change) the configuration
parameters for each logon session: for example, for each user ID. These
altered configuration parameters can then be returned to the TACL process.
Regardless of the setting, when a LOGOFF command has been executed and
followed (at some point) by a LOGON command or when a noninteractive
TACL process is started, the TACL process requests configuration information
from the $CMON process.
STOPONFEMODEMERR [ OFF | ON ]
ON specifies that TACL stops when error 140 (FEMODEMERR) is
encountered on its input. If the TACL process was started with the PORTTACL
startup parameter, this TACL configuration setting is ignored. (TACL goes to
the logged off state and waits for a modem connect message when error 140 is
encountered.) The default is OFF, meaning TACL is put in a logged off state
and waits for a modem connection message when an error 140 is
encountered.
tacl-image-name
is the name of an existing TACL image file to be configured. You must that ensure
a copy of TACL is created before trying to configure it, because TACL does not
create the copy. If you omit tacl-image-name, the built-in function
#SETCONFIGURATION configures the currently running TACL process and the
new configuration values are used for later operations that require these
configuration values.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-349
# S E T C O N F IG U R A T IO N B uilt-In F u nctio n
Result
#SETCONFIGURATION returns zero if it configures the TACL image or itself
successfully; otherwise, it returns these values:
-2
SETCONFIGURATION error
-1
>0
In addition, the built-in variable #ERRORNUMBERS is set when an error occurs while
executing the #SETCONFIGURATION built-in function (there is no text output):
1165 error-detail-1 error-detail-2 0
The example following this description shows how to code #ERRORNUMBERS with
#SETCONFIGURATION to determine the error. This table describes possible
#ERRORNUMBERS values:
errordetail-1
errordetail-2
Cause
Effect
Recovery
filesystem
error
Depends on the
error
Requested
operation fails.
Requested
operation fails.
None
None
Requested
operation fails.
Requested
operation fails.
None
None
None
Requested
operation fails.
Too many
configuration options
Requested
operation fails.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-350
# S E T C O N F IG U R A T IO N B uilt-In F u nctio n
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-351
# S E T C O N F IG U R A T IO N B uilt-In F u nctio n
If your installation uses $CMON processes and you want to take advantage of the
STOPONFEMODEMERR behavior, your $CMON program must be changed to
specifically include the new configuration parameter.
Example
?TACL MACRO
#FRAME
#PUSH configuration^error
==Make a duplicate TACL from the current TACL
FUP DUP $SYSTEM.SYSTEM.TACL, NEWTACL
==Secure the current TACL so no other users can access it.
FUP SECURE $SYSTEM.SYSTEM.TACL, ----
==Configure the new TACL with the appropriate options
#SET configuration^error [#SETCONFIGURATION/BLINDLOGON OFF, &
CMONTIMEOUT 50/ NEWTACL]
[#IF configuration^error |THEN|
== Pick up individual error fields:
#PUSH tacl^error error^detail1 error^detail2
#SETMANY tacl^error error^detail1 error^detail2,
[#ERRORNUMBERS]
[#CASE [error^detail1]
|1| error [error^detail2] == File system error
|2| #OUTPUT *ERROR* Not user 255, 255 == Security violation
|3| #OUTPUT *ERROR* Incorrect TACL image == vproc error
|4|
== Configuration error
#OUTPUT *ERROR* Unable to fully configure TACL image
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-352
# S E T M A N Y B uilt-In F u nctio n
Result
#SETMANY returns nothing.
Considerations
Each item in text is put into the corresponding variable level. If, however, the
corresponding entry in variable-name-list is an underscore character (_)
instead of a variable level name, the text item is discarded.
If there are more items in text than there are entries in variable-name-list,
the extra items are ignored. If there are more entries in variable-name-list
than items in text, the unallocated variable levels are cleared.
Specified variable levels must already exist; their types remain unchanged.
To copy a string to an existing variable level, use the #SETV built-in function.
To change the contents of a single variable level or built-in variable, use the #SET
built-in function.
Examples
1. This example illustrates the use of #SETMANY to find out the four parts of a file
name:
[#SETMANY volume subvol file system,
[#FILEINFO /VOLUME,SUBVOL,FILE,SYSTEM/ fname]
]
The SYSTEM option is specified last because it returns nothing if the file name is
in local form and would cause the correspondence between the two lists to be lost
if it did not occur last.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-353
# S E T M A N Y B uilt-In F u nctio n
2. This example shows how to find the numeric portion of the current operating
system RVU:
#SETMANY _ number , [#TOSVERSION]
#TOSVERSION returns a letter, a space, and a number; the underscore causes
the letter in the #TOSVERSION result to be discarded.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-354
# S E T P R O C E S S S T A T E B uilt-In F u nctio n
# S E T P R O C E S S S T A T E B uilt-In F u nctio n
value of 0 for the current TACL process indicates that the INHERITEDLOGON
state of the local child TACL process will be 0. The new process will start in the
logged-off state. The default value is 0.
Remote descendent TACL processes always start in a logged-off state.
You can clear the PROPAGATELOGON state flag in the current TACL process,
which causes local descendent TACL processes to start in a logged-off state
and prompt for logon. Remote descendent TACL processes always start in a
logged-off state.
PROPAGATESTOPONLOGOFF
specifies how local child TACL processes stop. A value of 1 for the current
TACL process indicates that the STOPONLOGOFF state of the child TACL
process will be 1. The child process will stop when it enters a logged-off state.
A value of 0 for the current TACL process indicates that the STOPONLOGOFF
state of a local child process will be 0. The child process will prompt for logon
information when it enters a logged-off state. The default value is 0.
If you set the PROPAGATESTOPONLOGOFF flag to 1, local descendent
TACL processes are stopped when they enter a logged-off state.
For remote child TACL processes, the parent process propagates a value of 0
for the STOPONLOGOFF flag.
Results
The #SETPROCESSSTATE built-in function returns a zero, indicating success, or a
positive number indicating a file system error.
If the user does not have sufficient privilege (as in a security violation), TACL returns a
file system error 48. This error indicates that the user cannot alter the state, although
the user may be the owner of the TACL process.
Considerations
The term TSN-TACL refers to a TACL process that Safeguard software starts after
authenticating the user of the TACL process.
For security reasons, most process state flags cannot be altered by non-privileged
users. Table 9-13 on page 9-357 describes valid operations:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-356
# S E T P R O C E S S S T A T E B uilt-In F u nctio n
Flag
Regular TACL
Process
TSN-TACL
Process
LOGGEDON
K.A.
K.A.
STOPONLOGOFF
PROPAGATELOGON
Can be cleared
but not set
Can be cleared
but not set
Can be cleared
but not set
PROPAGATESTOPONLOGOFF
TSNLOGON
Cannot be set or
cleared
Cannot be set or
cleared
Cannot be set or
cleared
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-357
#S E T S C A N B uilt-In F u nctio n
Result
#SETSCAN returns nothing.
Considerations
To obtain the number of characters that #ARGUMENT has processed, use the
#GETSCAN built-in function.
To determine whether an entire argument set has been processed, use the
#MORE built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-358
Mode
Source
Operator input
Absolute GMT
Hardware clock
Relative GMT
Operator input
Relative GMT
Hardware clock
Relative GMT
Force set
Relative GMT
Force adjustment
Absolute GMT
Force set
Ignored, optional
Rate adjustment
Adjust rate
10
Ignored, optional
tuid
is a time update ID obtained from #JULIANTIMESTAMP; use it with modes 2 and 3
to avoid conflicting changes.
Result
#SETSYSTEMCLOCK returns zero if it sets the system clock successfully; otherwise,
it returns a negative error result. If the system library contains the
SYSTEMCLOCK_SET_ Guardian procedure, #SETSYSTEMCLOCK returns the error
result defined in the "Result Codes (Error Returns)" subsection of the
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-359
Considerations
Example
This example calls #SETSYSTEMCLOCK and returns an error if you do not have
super-group capability:
#FRAME
#PUSH tstamp
[#IF [#SETSYSTEMCLOCK tstamp 0] |THEN|
#OUTPUT System time not changed. Insufficient capability.
]
#UNFRAME
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-360
# S E T V B u ilt-In F un ctio n U se
Result
#SETV returns nothing.
Considerations
If the destination variable is of a different type than the source variable, the
destination variable inherits the type as well as the contents of the source variable.
If a variable maintains a connection to a file, device, or process, such as a
connection established by #REQUESTER, and #SETV sets the variable to a new
value, the original connection is dropped because TACL deletes the original
contents of the variable.
When the source string is a structure, the destination variable level becomes a
structure like the source structure and contains its own copy of the data.
To change the contents of a variable level or built-in variable, use the #SET built-in
function.
To distribute the members of a space-separated list into several individual variable
levels, use the #SETMANY built-in function.
Example
This example shows a combination of a variable name and quoted text in the source
string:
#PUSH var termname
#SET termname [#MYTERM]
#SETV var "My terminal is " '+' termname '+' " at this time."
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-361
# S E T V B u ilt-In F un ctio n U se
Assuming that the home terminal is named $HAPPY at the time the #SET function is
invoked, var then contains:
My terminal is $HAPPY at this time.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-362
# S H IF T D E F A U LT B u ilt-In V a ria b le
Result
#SHIFTDEFAULT returns DOWN, NOOP, or UP.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-363
# S H IF T S T R IN G B uilt-In F u nctio n
Result
#SHIFTSTRING returns the text argument, shifted as specified.
Considerations
If you do not specify a shift direction, it defaults to the current value-DOWN, NOOP,
or UP-of the #SHIFTDEFAULT built-in variable.
If you specify the NOOP option, or if the current #SHIFTDEFAULT setting is NOOP,
#SHIFTSTRING does nothing.
If the CPRULES0 character-processing rules are in effect, a number of lowercase
characters (but not all) in the upper half of the international character set lose their
diacritical marks when upshifted. Subsequent downshifting does not restore them.
For example:
Upshift
Downshift
i = IU
IU = iu
When the CPRULES1 rules are in effect, diacritical marks remain intact when
characters that have them are upshifted.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-364
# S H IF T S T R IN G B uilt-In F u nctio n
Example
This example illustrates the use of #SHIFTSTRING to shift the case of a variable level:
62> #PUSH vara
63> #SET vara this is a test
64> #OUTPUT [#SHIFTSTRING /UP/ [vara]]
THIS IS A TEST
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-365
#S O R T B uilt-In F u nctio n
Result
#SORT returns a sorted space-separated list.
Considerations
Examples
1. This example illustrates the use of #SORT on a specified list of characters:
65> [#DEF pogo TEXT |BODY| albert howland churchy
grundoon]
66> #OUTPUT [#SORT /DESCENDING/ [pogo]]
albert churchy grundon howland
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-366
#S O R T B uilt-In F u nctio n
2. This example illustrates the way in which equal-valued uppercase and lowercase
characters are sorted.
67> #OUTPUT [#SORT /ASCENDING/ a B b A]
a A B b
3. These examples show the influence of character-processing rules. The first
instance shows the result when the CPRULES0 rules, which cause a number of
international characters to lose their diacritical marks when upshifted, are in effect:
68> #OUTPUT [#SORT /ASCENDING/ B a a A b]
a A B b
The second instance shows the result when CPRULES1 rules, under which
diacritical marks remain intact during upshifting, are in effect:
69> #OUTPUT [#SORT /ASCENDING/ B a A b]
a A B b
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-367
# S P IF O R M A T C LO S E B uilt-In F u nctio n
Result
#SPIFORMATCLOSE returns nothing.
Consideration
TACL opens the formatter template file associated with =_EMS_TEMPLATES
automatically whenever you invoke a built-in function that uses a formatter file (such as
#EMSTEXT or #EMSINIT). You can use the #SPIFORMATCLOSE built-in function to
close the EMS formatter template file so that you can change the
=_EMS_TEMPLATES DEFINE and open a new template file.
For more information, see the DSM Template Services Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-368
# S S G E T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-369
# S S G E T B uilt-In F u nctio n
get-op
is one of these:
token-code
directs #SSGET to return the token value or values associated with tokencode. If token-code is a token that marks the beginning of a list, #SSGET
selects the list so that subsequent calls can retrieve tokens within the list. If
token-code is ZSPI^TKN^ENDLIST, #SSGET pops out of the list.
token-code can be any of the header tokens described for the #SSGET
Built-In Function on page 9-369 and #SSGETV Built-In Function on
page 9-374. You can also supply the token ZSPI^TKN^DEFAULT^SSID to
obtain the default subsystem ID at the current position.
ZSPI^TKN^COUNT c-token-id
directs #SSGET to return the number of occurrences of the token specified by
the token code or the token map c-token-id, starting with the occurrence
specified by index. To count all occurrences in the current list, specify an index
of 1.
If c-token-id is omitted or equal to ZSPI^VAL^NULL^TOKENCODE, and
index is omitted or zero, #SSGET counts occurrences of the current token
beginning with the current occurrence.
ZSPI^TKN^LEN l-token-id
directs #SSGET to return the byte length of the token specified by the token
code or token map l-token-id. This is the size of the buffer needed to
contain the stated occurrence of the token value. For variable-length token
values, this includes the two bytes required for the length word: The byte
length returned is token-value[0]+2.
If you omit this option, or if l-token-id is equal to
ZSPI^VAL^NULL^TOKENCODE, and index is omitted or zero, #SSGET
returns the length of the current occurrence of the current token.
If l-token-id is a token map, this operation returns the length contained in
that map; the actual value in the buffer can differ from this length. To get the
actual length of the token value in the buffer, invoke #SSGET with
ZSPI^TKN^LEN and a token code made up of ZSPI^TYP^STRUCT and the
token number from the token map. This invocation returns the length of the
structure value, including two bytes for the length field. Subtract 2 from this
value to get the length of the value itself.
ZSPI^TKN^NEXTCODE
directs #SSGET to return the next token code that is different from the current
token code, followed by the subsystem ID. The subsystem ID returned in the
result always has a version field of zero (null).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-370
# S S G E T B uilt-In F u nctio n
The index parameter has no effect on this operation, but if you supply it, it must
be zero.
ZSPI^TKN^NEXTTOKEN
directs #SSGET to return the very next token code, followed by the subsystem
ID. The subsystem ID returned always has a version field of zero (null).
This operation differs from ZSPI^TKN^NEXTCODE in that it always returns the
token code of the next token, whether it is the same as that of the current
token or different, and whether the token is within a list or not. The operation
returns multiple occurrences of the same token code in the same order as they
were added to the buffer with #SSPUT(V).
The index and count parameters have no effect on this operation, but if you
use index, it must be zero; count is always returned as 1 in this operation.
Note. The special operations ZSPI^TKN^NEXTCODE and ZSPI^TKN^NEXTTOKEN
return only token codes. In particular, note that tokens added to the buffer using
#SSPUTV with a token map are carried in the buffer with a token code of type
ZSPI^TYP^STRUCT. The NEXTCODE and NEXTTOKEN operations return that token
code, not the token map used with #SSPUTV.
ZSPI^TKN^OFFSET o-token-id
directs #SSGET to return the byte offset of the token specified by the token
code or token map o-token-id. The value returned is the offset from the
start of the buffer to the value associated with the specified token code and
index. (For variable-length values, the token value begins with the length word;
the offset given is the offset to that length word.)
If you omit this option or if o-token-id is equal to
ZSPI^VAL^NULL^TOKENCODE, and index is omitted or zero, #SSGET
returns the length of the current occurrence of the current token.
Note that you must supply appropriate token code definitions. TACL merely
keys off the numeric token codes for the special operations.
TACL supports the special semantics for only those SPI special token codes
shown; any other token codes are assumed to adhere to standard semantics.
Result
#SSGET returns a numeric status code indicating the outcome of the SSGET
procedure. If the status code is zero (no error), it is followed by a space and a spaceseparated list of the relevant SSGET results in the TACL external representation, as
follows:
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-371
# S S G E T B uilt-In F u nctio n
are returned in two parts-the byte length followed by the actual value-separated by
a space
Condition
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
-11
-12
Considerations
Tokens extracted by #SSGET are not deleted or removed from the buffer.
When the current position is within a particular list, all #SSGET calls pertain only to
tokens within that list (except that header fields are always accessible). You can
exit from the list by calling #SSGET to get the ZSPI^TKN^ENDLIST token.
When token-code is ZSPI^TKN^ENDLIST, the index and count parameters have
no effect. However, if you supply them, index must be 0 or 1; count is always
returned as 1.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-372
# S S G E T B uilt-In F u nctio n
Typ
Item Retrieved
ZSPI^TKN^CHECKSUM
INT
Checksum flag
ZSPI^TKN^COMMAND
ENUM
Command number
ZSPI^TKN^HDRTYPE
UINT
Header type
ZSPI^TKN^LASTERR
ENUM
ZSPI^TKN^LASTERRCODE
INT2
token-code, c-token-id, or
l-token-id on last error call
ZSPI^TKN^LASTPOSITION
BYTE:8
ZSPI^TKN^MAX^FIELD^VERSION
UINT
ZSPI^TKN^MAXRESP
INT
ZSPI^TKN^OBJECT^TYPE
ENUM
Object-type number
ZSPI^TKN^POSITION
BYTE:8
ZSPI^TKN^SERVER^VERSION
UINT
Server RVU
ZSPI^TKN^SSID
SSID
ZSPI^TKN^USEDLEN
UINT
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-373
#S S G E T V B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-374
#S S G E T V B uilt-In F u nctio n
result-var
is the name of the writable STRUCT into which #SSGETV is to store the data
returned. The original contents of the STRUCT are lost.
If the status code in the function result is zero (no error), the result stored in
result-var is as follows:
Result
#SSGETV returns a numeric status code indicating the outcome of the SSGET
procedure. The meaning of the status code is as follows:
Code
Condition
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
#S S G E T V B uilt-In F u nctio n
Considerations
Tokens extracted by #SSGETV are not deleted or removed from the buffer.
When the current position is within a particular list, all #SSGETV calls pertain only
to tokens within that list (except that header fields are always accessible). You can
exit from the list by calling #SSGETV to get the ZSPI^TKN^ENDLIST token.
When token-id is ZSPI^TKN^ENDLIST, the index and count parameters have
no effect. However, if you supply them, index must be 0 or 1; count is always
returned as 1.
When using #SSGETV with a token map for the token-id parameter, the map
can specify a structure version that is longer or shorter than the structure contained
in the buffer. If the requested version is longer than the version in the buffer,
#SSGETV calls SSNULL to set to null values the new fields that are not obtained
from the buffer. If the requested version is shorter than the one in the buffer,
#SSGETV returns only the requested length.
If the data returned by #SSGETV is longer than the data area of the STRUCT
identified by result-var, TACL discards the excess bytes without notification. If
the data is shorter than the data area of result-var, TACL sets the entire
STRUCT to its default values, then overwrites the beginning of the data bytes of
the STRUCT with the returned data. No type conversions of any kind are done.
Consequently, if the token retrieved is of type ZSPI^TYP^INT, for instance, and the
result-var STRUCT consists of a single field of type INT2, the token value
appears in the high-order 16 bits of the INT2 field, not the low-order 16 bits.
If you specified the COUNT option, TACL puts all occurrences of the token value
into the STRUCT exactly as returned by #SSGETV, subject to the size constraints
mentioned in the previous consideration. If the tokens are variable-length tokens,
each token value consists of a length word followed by the actual value, and the
actual value is word-aligned.
You can pass header tokens and one special operation in token-id to get
corresponding values. They are described under Header Tokens and Special
Operation for #SSGET and #SSGETV in the explanation of #SSGET.
Examples
1. This example shows how to declare STRUCTs that allow you to extract individual
fields of the token code or the subsystem ID returned by #SSGETV with the
ZSPI^TKN^NEXTCODE or ZSPI^TKN^NEXTTOKEN option:
?SECTION decompose_ssid STRUCT
BEGIN
SSID ss;
STRUCT z^ssid REDEFINES ss;
BEGIN
CHAR z^owner(0:7);
INT z^number;
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-376
#S S G E T V B uilt-In F u nctio n
UINT z^version;
END;
END;
?SECTION nexttoken_return STRUCT
BEGIN
STRUCT tkn ; LIKE zspi^ddl^tokencode;
STRUCT ssid; LIKE decompose_ssid;
END;
?SECTION nextcode_return STRUCT
BEGIN
STRUCT tkn ; LIKE zspi^ddl^tokencode;
INT contiguous_occurrences;
STRUCT ssid; LIKE decompose_ssid;
END;
2. This routine uses these STRUCT declarations to compare two subsystem IDs
returned by #SSGETV with ZSPI^TKN^NEXTCODE or ZSPI^TKN^NEXTTOKEN,
ignoring the version field:
?SECTION same_ssid ROUTINE == <ssid1> <ssid2>
== Returns TRUE if two SSIDs are the same except for
== the version field
#FRAME
#PUSH sstext
#DEF ss1 STRUCT LIKE decompose_ssid;
#DEF ss2 STRUCT LIKE decompose_ssid;
#IF{SINK} [#ARGUMENT/VALUE sstext/ SUBSYSTEM]
#SET ss1 [sstext]
#IF{SINK} [#ARGUMENT/VALUE sstext/ SUBSYSTEM]
#SET ss2 [sstext]
#RESULT [#COMPUTE [#COMPAREV ss1:z^ssid:z^owner(0:7)
ss2:z^ssid:z^owner(0:7)]
AND [#COMPAREV ss1:z^ssid:z^number
ss2:z^ssid:z^number] ]
#UNFRAME
{same_ssid}
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-377
#S S IN IT B uilt-In F u nctio n
#S S IN IT B uilt-In F u nctio n
many response records as can fit in the buffer, each enclosed in a list. If you
omit this option, it defaults to zero.
OBJECT num
is the object type. If you omit this option, it defaults to
ZSPI^VAL^NULL^OBJECT^TYPE (zero).
SERVERVERSION num
is the server version number, normally provided only by subsystems or by
other programs or functions that act as servers. This number is a 16-bit
unsigned integer value representing the RVU of the subsystem or server.
SSINIT puts this value in the header token ZSPI^TKN^SERVER^VERSION for
use in RVU compatibility checking. If you omit this option, the server RVU
defaults to zero.
Result
#SSINIT returns a numeric status code indicating the outcome of the SSINIT
procedure, as follows:
Code
Condition
No error
-2
-3
Missing parameter
-4
-5
Buffer full
-7
Internal error
-10
Invalid subsystem ID
-12
Consideration
For the SSID parameter, you generally use the subsystem ID defined by the target
subsystem. For most subsystems, the subsystem ID has a name of the form
subsys^VAL^SSID.
Example
Here is an example using the TMF subsystem:
#SSINIT buf [ZTMF^VAL^SSID] [ZSPI^VAL^GETVERSION]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-379
#S S M O V E B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-380
#S S M O V E B uilt-In F u nctio n
source-var
is the name of the source message buffer variable level, from which the specified
token or tokens are to be copied. source-var must be a writable STRUCT that
has been initialized with #SSINIT.
dest-var
is the name of the destination message buffer variable level, to which the specified
token or tokens are to be copied. dest-var must be a writable STRUCT that has
been initialized with #SSINIT.
token-id
is a token code or a token map that identifies the token to be moved. That token
must be present in the source buffer. The token ID can refer to a simple token, an
extensible structured token, or a list token. If token-id identifies a list token,
#SSMOVE moves that token, its associated end-list token, and all tokens in
between.
Result
#SSMOVE returns a numeric status code indicating the outcome of the SSMOVE
procedure, as follows:
Code
Condition
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
-11
-12
If the status code is zero (no error), it is followed by a space and the count of the token
values or lists moved.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-381
#S S M O V E B uilt-In F u nctio n
Considerations
#SSMOVE does not alter any tokens copied from the source buffer.
After a successful copy, #SSMOVE changes the source buffer position for a
subsequent #SSGET(V) to the position of the last token moved.
When #SSMOVE copies a token identified by a token map, it truncates or pads the
value according to the map specifications, and adjusts the
ZSPI^TKN^MAX^FIELD^VERSION header field of the destination buffer
appropriately.
You can use #SSMOVE to move an incomplete list (one with no end-list token) if,
and only if, you omit the DINDEX option or specify dest-index as zero. If you
supply a nonzero dest-index, meaning that you are requesting a replacement
operation, an incomplete list causes #SSMOVE to return a token not found status
code (-8).
If an error occurs on #SSMOVE, you can set the ZSPI^TKN^LASTERR and
ZSPI^TKN^LASTERRCODE indications in either the source buffer or the
destination buffer, depending on whether the error occurred on the logical
#SSGETV or #SSPUTV part of the copy.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-382
#S S N U L L B uilt-In F u nctio n
Result
#SSNULL returns a numeric status code indicating the outcome of the SSNULL
procedure, as follows:
Code
Condition
No error
-3
Missing parameter
-4
-7
Internal error
-9
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-383
# S S P U T B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-384
# S S P U T B uilt-In F u nctio n
token-value
is the token value in external representation. Its data representation is determined
by the token-type field of token-code.
Result
#SSPUT returns a numeric status code indicating the outcome of the SSPUT
procedure, as follows:
Code
Condition
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
-11
-12
Considerations
You can omit the token-value parameter if the token length specified by tokencode is zero; otherwise, the token-value parameter is required.
Specifying a count value greater than 1 is equivalent to calling #SSPUT count
times in succession without the COUNT option (but supplying a new token-value
before each call).
If count is greater than 1 and the token is of variable length, each token value must
be an even number of bytes in length to ensure word alignment.
The order in which tokens are added to the buffer is not significant, except in the
cases of:
#SSPUT calls that start and end lists (using tokens such as
ZSPI^TKN^DATALIST, ZSPI^TKN^ERRLIST, and ZSPI^TKN^ENDLIST).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-385
# S S P U T B uilt-In F u nctio n
Adding a token to the buffer with #SSPUT does not affect the current position for
subsequent calls to #SSGET or #SSGETV.
Typ
Item retrieved
ZSPI^TKN^CHECKSUM
INT
ZSPI^TKN^CLEARERR
none
ZSPI^TKN^DATA^FLUSH
none
ZSPI^TKN^DELETE
INT2
ZSPI^TKN^INITIAL^POSITION
INT
ZSPI^TKN^MAXRESP
INT
ZSPI^TKN^POSITION
BYTE:8
ZSPI^TKN^RESET^BUFFER
UINT
Resets maximum buffer length, clear lasterror information, and reset position to
start in an SPI buffer received from
another process
ZSPI^TKN^SERVER^VERSION
UINT
ZSPI^TKN^CHECKSUM
INT
For some of these tokens, when you pass them to #SSPUT or #SSPUTV in the tokencode parameter, special considerations apply to other parameters involved.
ZSPI^TKN^CHECKSUM. Use this token code with a nonzero token-value to
enable checksum protection of the data portion of the buffer; use a zero token-value
to disable it (the header is always protected by a checksum).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-386
# S S P U T B uilt-In F u nctio n
# S S P U T B uilt-In F u nctio n
If token-value is less than the actual number of bytes used in the buffer, as given in
the header token ZSPI^TKN^USEDLEN, this operation returns an SPI error -5 (buffer
full). SPI still resets the maximum buffer length in the SPI message header, causing
subsequent calls for that buffer to fail with error -1 (invalid buffer format).
ZSPI^TKN^SERVER^VERSION. Use this token code to set the header field
containing the RVU of the server. For token-value, supply an unsigned integer that
represents the appropriate RVU. For example, if the server is a running RVU C20,
specify token-value as the unsigned integer 17172, representing a C (character
number 67) in the left byte (256 x 67 = 17152) and 20 in the right byte.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-388
# S S P U T V B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-389
# S S P U T V B uilt-In F u nctio n
Result
#SSPUTV returns a numeric status code indicating the outcome of the SSPUT
procedure, as follows:
Code
Condition
No error
-1
-2
-3
Missing parameter
-4
-5
Buffer full
-6
Invalid checksum
-7
Internal error
-8
-9
-10
Invalid subsystem ID
-11
-12
Considerations
If the token length specified by token-id is zero, you must supply a variable level for
source-var, but its contents do not matter.
Specifying a count parameter greater than 1 for #SSPUTV is equivalent to calling
#SSPUTV count times without the COUNT option (but supplying a new tokenvalue before each call).
The order in which tokens are added to the buffer is not significant except in the
cases of:
#SSPUTV calls with token codes for tokens that start and end lists
(ZSPI^TKN^DATALIST, ZSPI^TKN^ERRLIST, ZSPI^TKN^LIST, and
ZSPI^TKN^ENDLIST).
If the data in source-var is longer than the data area provided by #SSPUTV, the
excess bytes are ignored without any notification. If the data in source-var is
shorter than the data area provided, #SSPUTV sets the remainder of the token
value to unspecified values.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-390
# S S P U T V B uilt-In F u nctio n
If you specify the COUNT option, #SSPUTV expects the value of source-var to
be an array of count values of the type of token-value. Variable-length token
values must be word-aligned.
Adding a token to the buffer with #SSPUTV does not affect the current position for
subsequent calls to #SSGET or #SSGETV.
When you supply a token map for token-id, #SSPUTV uses the version and nullvalue information in the token map, if necessary, to update the header token
ZSPI^TKN^MAX^FIELD^VERSION. The token map is not stored in the buffer;
instead, #SSPUTV creates a token code consisting of token type
ZSPI^TYP^STRUCT and the token number from the map.
SPI defines a number of token codes for use with #SSPUT and #SSPUTV to set
the values of header tokens and perform special operations. These are described
in the Section 8 under Header Tokens and Special Operations for #SSPUT and
#SSPUTV in the description of the #SSPUT built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-391
# S T O P B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-392
# S T O P B uilt-In F u nctio n
text
is text, 1 to 80 characters, for the process deletion message. Leading and trailing
spaces are suppressed.
Result
If you do not specify the ERROR option, the #STOP built-in function returns 0 if the
STOP system procedure cannot make a successful request to stop the process. If the
request is submitted successfully, #STOP returns -1. The designated process might or
might not be stopped, depending on the stop mode of the process and the authority of
the caller.
If you include the ERROR option, the #STOP built-in function returns the file-system
error code passed to it by the STOP system procedure. In this case, zero indicates no
error. The #STOP built-in function returns 638 or 639 if the process is queued for
stopping but has not actually stopped.
If #STOP stops the TACL process from which you issued it, #STOP returns its result
but the TACL process cannot receive it.
Considerations
A successful #STOP result does not indicate that the process has stopped. A
successful result indicates that the stop request was submitted successfully.
If the process cannot be terminated immediately, the STOP system procedure
queues the request.
If you omit the process designation (process name or CPU,PIN) #STOP stops the
current default process (the process last started by TACL or for which TACL most
recently paused), if it is still running. If there is no current default process, you must
include the process designation. You can examine the default process with the
#PROCESS built-in function.
You must supply the process designation if you wish to include the text argument.
COMPLETIONCODE, SUBSYS, TERMINATIONINFO, and text are ignored,
except when terminating your current TACL process (or, if it is a process pair,
either its primary or backup process). If you are stopping your TACL, those items
you specify are included in the stop system message.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-393
#S U S P E N D P R O C E S S B uilt-In F u nctio n
Result
#SUSPENDPROCESS returns a nonzero value if successful; otherwise, it returns
zero.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-394
#S W IT C H B uilt-In F u nctio n
Considerations
Your TACL must have a backup process. To create a backup process, include a
backup specification in the #NEWPROCESS call or RUN command, or use the
BACKUPCPU command.
Do not include #SWITCH in an IN file specified in a command to run TACL; if you
do so, TACL performs the switch before processing other commands-and each
switch causes an initialization-so that the TACL process continues to switch
processors.
#SWITCH establishes an initial logon state, resetting all ASSIGNs, PARAMs, and
DEFINEs, invoking the TACLLOCL file and your TACLCSTM file, and setting the
history buffer index to 1.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-395
#S Y S T E M B uilt-In F u nctio n
Result
#SYSTEM returns nothing.
Considerations
If you omit \node-name, your saved default system becomes your current default
system.
If you are running a remote TACL process, entering SYSTEM with no following
parameters establishes that remote system (not the local system to which your
terminal is connected) as your current default system.
These function calls are not equivalent:
14> #SYSTEM \ local-node-name
14> #SYSTEM
The first invocation causes the network restrictions on file-name lengths to take
effect; the second does not. See the Expand Network Management and
Troubleshooting Guide for information on network file-name restrictions.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-396
# S Y S T E M N A M E B uilt-In F u nctio n
Result
#SYSTEMNAME returns the name of the system if the system can be reached, -2 if all
paths to the system are down, or -1 if the system is not defined.
Consideration
To obtain the network node number of a system, use the #SYSTEMNUMBER built-in
function.
Example
These code tests for system availability and displays the node name if the system is
available:
?SECTION getname MACRO
#PUSH name
#SET name [#SYSTEMNAME %1%]
[#CASE [name]
| -2 | #OUTPUT System %1% is not available
| -1 | #OUTPUT System %1% is not defined
|OTHERWISE| #OUTPUT System %1% (node name [name]) is &
available
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-397
#S Y S T E M N U M B E R B uilt-In F u nctio n
Result
#SYSTEMNUMBER returns the number of the system if the system can be reached, -2
if all paths to the system are down, or -1 if the system is not defined.
Consideration
To obtain the name of a system, use the #SYSTEMNAME built-in function.
Example
These code tests for system availability and displays the system number if the system
is available:
?SECTION getnum MACRO
#PUSH num
#SET num [#SYSTEMNUMBER %1%]
[#CASE [num]
| -2 | #OUTPUT %1% is not available
| -1 | #OUTPUT %1% is not defined
|OTHERWISE| #OUTPUT %1% (system number [num]) is &
available
]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-398
#T A C L O P E R A T IO N B uilt-In F u nctio n
Result
#TACLOPERATION returns REQUESTER or SERVER depending on whether TACL is
receiving its command stream from IN (REQUESTER) or $RECEIVE (SERVER).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-399
# T A C L S E C U R IT Y B u ilt-In V a ria b le
Result
#TACLSECURITY returns a pair of characters, enclosed in quotes, that represent the
current TACL security. The first character represents the criterion that determines
whether to allow a process to open the TACL processs $RECEIVE for writing. The
second character determines whether to allow an opener with a qualifying name to
transfer data to or from a #SERVER. For example:
13> #TACLSECURITY
#TACLSECURITY expanded to:
"NN"
The characters are the same as for operating system file security. They are as follows:
O
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-400
# T A C L S E C U R IT Y B u ilt-In V a ria b le
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-401
# T A C LV E R S IO N B uilt-In F u nctio n
Result
With the REVISION option, #TACLVERSION returns only the RVU-level portion of the
version identifier, followed by a revision level identifier, in the form:
Xnn nnnn
where Xnn is the RVU identifier (C20, for example) and nnnn is a four-digit number
identifying the revision level within that RVU. That number is incremented whenever an
interim product modification is made to the RVU.
This form of revision number can be collated. For example, if a macro operation
depends on a feature released in a particular RVU of TACL, such as C20 0011, the
macro can test to see if the current RVU is equal to or greater than that RVU:
[#IF "[#TACLVERSION/REVISION/]" '>=' "C20 0011" |THEN| ...
Without the REVISION option, #TACLVERSION returns the current TACL RVU
identifier.
Examples
1. This example illustrates the result of #TACLVERSION:
17> #OUTPUT [#TACLVERSION]
T9205D30 - 26MAR1999
1. This code disassembles a complete TACL RVU:
[#DEF break^version MACRO |BODY|
== First argument is var-level to receive product
== Second argument is var-level to receive version
== Third argument is var-level to receive date
#FRAME
== Make a structure to allow access to individual
== characters:
[#DEF tv STRUCT
BEGIN
CHAR fld (0:19)
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-402
# T A C LV E R S IO N B uilt-In F u nctio n
END;
]
== Put TACL version into the structure
#SET tv [#TACLVERSION]
== Obtain the fields
#SET %1% [tv:fld(0:4)] == T9205 Product number
#SET %2% [tb:fld(5:7)] == Xnn Version
== Ignore 8:10 == " - " (formatting)
#SET %3% [tv:fld(11:19)] == ddMMMyyyy Date
== Clean up and exit
#UNFRAME
]
To use this macro, define variables to hold the components of the TACL product
number and invoke the macro to assign those components:
12> #PUSH product version date
13> BREAK^VERSION product version date
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-403
#T IM E S T A M P B uilt-In F u nctio n
Result
#TIMESTAMP returns the result of the TIMESTAMP operating system procedure.
Consideration
You can convert the result of #TIMESTAMP to a numeric date and time by using
#CONTIME.
Example
This example illustrates the #TIMESTAMP result:
15> #OUTPUT [#TIMESTAMP]
16> 39950986284
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-404
# T O S V E R S IO N B uilt-In F u nctio n
Result
#TOSVERSION returns the result of the TOSVERSION operating system procedure, in
the form character-space-number. For example:
27> #TOSVERSION
#TOSVERSION expanded to:
M 20
Considerations
If you omit \node-name, #TOSVERSION returns the RVU of the operating system
running on the default system.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-405
# T R A C E B u ilt-In V a ria b le
Result
#TRACE returns -1 (true) if the flag is on, 0 (false) if the flag is off.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-406
# U N F R A M E B uilt-In F u nctio n
Result
#UNFRAME returns nothing.
Note. ATTACHSEG operates by pushing and defining a directory variable that refers to the
specified segment file; DETACHSEG operates by popping that directory variable. Because
#UNFRAME pops all variables pushed since the most recent #FRAME, if you attach a segment
file following a #FRAME, the corresponding #UNFRAME detaches the segment file; its
contents are no longer available. Subsequent attempts to invoke those contents result in
errors.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-407
# U S E L IS T B u ilt-In V a ria b le
Result
#USELIST returns a space-separated list of full path names of the directories in your
use list.
Considerations
Use #PUSH #USELIST (or PUSH #USELIST) to save a copy of the current use
list.
Use #POP #USELIST (or POP #USELIST) to restore the use list from the last copy
pushed.
Use #SET #USELIST (or SET VARIABLE #USELIST) to assign directory names to
the use list.
The syntax of #SET #USELIST is:
#SET #USELIST [ directory-name [ directory-name ] ... ]
directory-name
is the name of a directory variable level to be put in the use list.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-408
# U S E R ID B uilt-In F u nctio n
Result
#USERID returns the user ID of the specified user, if that user is defined; otherwise, it
returns nothing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-409
#U S E R N A M E B uilt-In F u nctio n
Result
#USERNAME returns the user name of the specified user, if that user is defined on the
system; otherwise, it returns nothing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-410
# V A R IA B LE IN F O B uilt-In F u nctio n
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-411
# V A R IA B LE IN F O B uilt-In F u nctio n
OFFSET
returns the number of bytes between the beginning of the structure and the first
byte of data of the specified variable level (if the specified variable level is a
STRUCT item).
PROCESS
returns the process identification associated with the specified variable level by
means of an implicit server.
REQUESTER
returns the file name associated with the specified variable level, if it is used as
a requester variable.
SEGMENT
returns the name of the segment file that contains the variables of a directory, if
variable-level is a directory and its variables are in a different segment file
from that in which variable-level resides. In all other cases, this option is
inoperative.
SERVER
returns the server process name associated with the specified variable level, if
that variable level is used as an explicit server variable.
TYPE
returns the type of the variable level.
VARIABLE
returns the name of the specified variable, stripped of any level-number
identification.
variable-level
is the name of the variable level about which you are requesting information.
Result
#VARIABLEINFO returns a space-separated list of the requested information about the
variable level.
In the case of the LEN, LINES, OCCURS, OFFSET, and TYPE options, the information
returned is a function of the type of variable level involved.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-412
# V A R IA B LE IN F O B uilt-In F u nctio n
Table 9-16 lists the result for each of these options depending on the type of argument
given to #VARIABLEINFO.
Table 9-16. #VARIABLEINFO Type-Dependent Results
Variable Type
LEN
LINES
OCCURS
OFFSET
TYPE
Alias
ALIAS
Delta
(a)
(b)
DELTA
Directory
DIRECTORY
Macro
(a)
(b)
MACRO
Routine
(a)
(b)
ROUTINE
Structure
(c)
STRUCT
Structure Item
(d)
(e)
(f)
(g)
Text
(a)
(b)
TEXT
Considerations
The information is returned in the order in which the options are given.
If the specified variable level does not exist, all options except EXISTENCE return
nothing.
When you apply the LINES or OCCURS option to a DELTA, MACRO, ROUTINE,
or TEXT variable level, the entire variable level must be read to compute the
specified values.
OCCURS and LEN ignore bounds specifications when operating with a STRUCT
item.
Each logical line within a variable contains an internal end-of-line character that
counts as one byte. For variables that contain TACL statements, each square
bracket ([,]), vertical bar (|), or tilde-space combination (~_) uses two bytes,
including unprintable characters that are subject to change from one TACL RVU to
another. Other characters use one byte.
If you are using #SETMANY to assign a number of results from #VARIABLEINFO
to several variable levels, put those options that can return empty results at the
end of the options to prevent losing the correlation between the two lists.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-413
#V A R IA B L E S B uilt-In F u nctio n
Result
Considerations
The variable name list is not alphabetically ordered, but you can use the #SORT
built-in function to make it so.
To obtain the names of variables and store them into a variable level, use the
#VARIABLESV built-in function.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-414
#V A R IA B L E S V B uilt-In F u nctio n
Result
#VARIABLESV returns nothing.
Considerations
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-415
# W A IT B uilt-In F u nctio n
Result
#WAIT returns the name and level number of the first variable level that is ready.
Considerations
These guidelines apply to the use of the #WAIT built-in function:
If you want to ensure that #WAIT always returns immediately, create an additional
variable level, not used for I/O, and specify its name last in the WAIT list.
To access only the topmost level of a variable, regardless of its level number, you
could invoke the #WAIT function as follows:
#PUSH error^var read^var prompt^var
[#CASE [#VARIABLEINFO /VARIABLE/
[#WAIT error^var read^var prompt^var] ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-416
# W A IT B uilt-In F u nctio n
When waiting for a prompt variable, be sure to clear the variable before initiating
the read and #WAIT operations. Otherwise, the variable might be ready despite the
outcome of your operation. For an example, see the TACL Programming Guide.
To provide thorough error handling when using processes and files accessed by
#REQUESTER or #SERVER, wait for all related variables.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-417
# W A K E U P B u ilt-In V a ria b le
Result
#WAKEUP returns the current state of the WAKEUP flag: -1 if the flag is on, 0 if it is off.
Considerations
num
is -1 to set the flag on and 0 to set it off.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-418
#W ID T H B u ilt-In V a ria b le
Result
#WIDTH returns the current setting of the width register.
Considerations
For D-series software RVUs, only the default number of characters or number of
characters set using the #set #width command are displayed. Excess characters
are truncated. For the default width (set to 80):
$DATA08 USERX 15> time
February 21, 2001 16:32:49
For G-series software RVUs, the number of characters indicates the number of
characters to be displayed on a line. Excess characters are displayed on a
subsequent line, and so forth. For width set to 10:
$DATA08 USERX 16> #set #width 10
$DATA08 USERX 17> time
February 2
1, 2001 16
:32:58
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-419
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
9-420
Syntax Summary
The syntax diagrams summarized in this appendix are divided into five categories:
The command interpreter set of commands and functions, supplied with TACL in
the directory :UTILS:TACL
The built-in functions and variables that constitute the TACL programming
language
The specialized forms of the #DEF function used to create and redefine structured
variables (STRUCT declarations)
The specialized forms of the #SET function used to assign values to TACL built-in
variables
The commands of the #DELTA character processor
Differences between H-series and G-series command syntax are noted in this section.
Differences between D-series and G-series, if any, may be found in the detailed syntax
contained in Section 8, UTILS:TACL Commands and Functions.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-1
S yn ta x S u m m ary
:U T ILS :T A C L C o m m a n ds an d F un ction s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-2
S yn ta x S u m m ary
:U T ILS :T A C L C o m m a n ds an d F un ction s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-3
S yn ta x S u m m ary
:U T ILS :T A C L C o m m a n ds an d F un ction s
S yn ta x S u m m ary
:U T ILS :T A C L C o m m a n ds an d F un ction s
G-Series RECEIVEDUMP
RECEIVEDUMP / OUT dump-file / cpu , fabric
[ , param [ , param ] ]
RELOAD [ / run-option [, run-option ] ... / ]
[ [ cpu-set [; cpu-set ]... ]
REMOTEPASSWORD [ \node-name [ , password ] ]
RENAME old-file-name [,] new-file-name
RESET DEFINE
{ { attribute-name [, attribute-name ]... } | * }
[ RUN[D] ] program-file [ / run-option [ , run-option ].../ ]
[ param-set ]
SEGINFO
SET DEFINE
{ attribute-spec | LIKE define-name }[, attribute-spec ]...
SET DEFMODE { ON | OFF }
SET HIGHPIN { ON | OFF }
SET INSPECT { OFF | ON | SAVEABEND }
SETPROMPT { SUBVOL | VOLUME | BOTH | NONE }
SET SWAP [ $volume-name ]
SETTIME
{ { month day } | { day month } } year , hour: min[: sec]
[ GMT | LST |LCT ]
SET VARIABLE [ / option [, option ]/ ] variable-level
[ text ]
SET VARIABLE built-in-variable [ built-in-text ]
SHOW [ / OUT list-file / ] [ attribute [ , attribute ] ... ]
SHOW [ / OUT list-file / ] DEFINE [ attribute-name | * ]
SINK [ text ]
STATUS [ / OUT list-file / ] [ range ] [ , condition ] ...
[ , DETAIL ] [ , STOP ]
STOP [ [\node-name.]{$process-name | cpu,pin } ]
SUSPEND [ [\node-name.]{$process-name | cpu,pin } ]
SWITCH
SYSTEM [ \node-name ]
SYSTIMES
[\node-name.]TACL [ / run-option [ , run-option ] ... / ]
[ backup-cpu-num ] [ ; parameter [ , parameter ] ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-5
S yn ta x S u m m ary
:U T ILS :T A C L C o m m a n ds an d F un ction s
TIME
USE [ directory-name [ [,] directory-name ] ... ]
USERS [ / run-option [ , run-option ] ... / ] [ range ]
VARIABLES [ directory-name ]
VARINFO [ variable [ [,] variable ] ... ]
VARTOFILE variable-level file-name
VCHANGE [ / option [ , option ] ... / ] variable-level
string-1 string-2 [ range ]
VCOPY [ / option [ , option ] ... / ] source-var range
dest-var dest-line
VDELETE [ / option [ , option ] / ... ] variable-level range
VFIND [ / option [ , option ] / ... ] variable-level string
[ range ]
VINSERT variable-level line-num
VLIST [ / option [ , option ] / ...] variable-level [ range ]
VMOVE [ / option [ , option ] / ... ] source-var range
dest-var dest-line
VOLUME [ [\node-name.] volume ] [ , "security" ]
VTREE [ directory-name ]
WAKEUP { ON | OFF }
WHO
{ X | Y }BUSDOWN from-cpu , to-cpu
{ X | Y }BUSUP from-cpu , to-cpu
! [ num | - num | text ]
? [ num | - num | text ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-6
S yn ta x S u m m ary
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-7
S yn ta x S u m m ary
S yn ta x S u m m ary
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-9
S yn ta x S u m m ary
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-10
S yn ta x S u m m ary
S yn ta x S u m m ary
#OUT
#OUTFORMAT
#OUTPUT [ / option [ , option ] ... / ] [ text ]
#OUTPUTV [ / option [ , option ] ... / ] string
#PARAM [ param-name ]
#PAUSE [ [\node-name.]{$process-name | cpu,pin } ]
#PMSEARCHLIST
#PMSG
#POP variable [ [,] variable ] ...
#PREFIX
#PROCESS
#PROCESSEXISTS [\node-name.]{$process-name | cpu,pin }
#PROCESSFILESECURITY
#PROCESSINFO / option [ , option ] ... /
[ [\node-name.]{$process-name | cpu,pin } ]
#PROCESSORSTATUS [ \node-name ]
#PROCESSORTYPE [ / BOTH | NAME / ]
{ { [\node-name.]{$process-name | cpu, pin } } | cpu-num
#PROMPT
#PURGE file-name
#PUSH variable [ [,] variable ]
#RAISE exception
#REPLYV string
#REQUESTER [ / option [ , option ] / ]
{ CLOSE variable-level }
{ READ file-name error-var read-var prompt-var } |
{ WRITE file-name error-var write-var }
#RESET option [ option ]
#REST
#RESULT [ text ]
#RETURN
#ROUTEPMSG { ALL | STANDARD |
( message-type [ message-type ] ... ) }
#ROUTINENAME
#SEGMENT [ / USED / ]
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-12
S yn ta x S u m m ary
S yn ta x S u m m ary
S T R U C T D eclaration s
#SYSTEMNUMBER \node-name
#TACLOPERATION
#TACLSECURITY
#TACLVERSION / REVISION /
#TIMESTAMP
#TOSVERSION [ \node-name ]
#TRACE
#UNFRAME
#USELIST
#USERID user
#USERNAME user
#VARIABLEINFO / option [ , option ] ... / variable-level
#VARIABLES [ / { BREAKPOINT | IO } / ]
#VARIABLESV [ / { BREAKPOINT | IO } / ] variable-level
#WAIT variable-level [ variable-level ] ...
#WAKEUP
#WIDTH
STRUCT Declarations
The following summarizes the forms of the #DEF function used to create and redefine
structured variables:
#DEF variable STRUCT
{ BEGIN declaration [ declaration ] ... END ; }
|
( LIKE structure-identifier ; }
type identifier [ VALUE initial-value ] ;
type identifier ( lower-bound : upper-bound )
[ VALUE initial-value ] ;
STRUCT identifier [ ( lower-bound : upper-bound ) ] ;
{ BEGIN declaration [ declaration ] ... END ; }
|
{ LIKE structure-identifier ; }
FILLER num ;
type identifier [ ( lower-bound : upper-bound ) ]
REDEFINES previous-identifier ;
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-14
S yn ta x S u m m ary
#S E T S um m ary
#SET Summary
The following summarizes the syntax of the #SET function when it is used to assign
values to built-in variables. SET VARIABLE commands used for the same purpose
have the same syntax.
#SET #ASSIGN [ [ / option [ , option ] ... / ] logical-unit ]
#SET #BREAKMODE { DISABLE | ENABLE | POSTPONE }
#SET #CHARACTERRULES file-name
#SET #DEFAULTS subvolume-name
#SET #DEFINEMODE { OFF | ON }
#SET #ERRORNUMBERS n n n n
#SET #EXIT num
#SET #HELPKEY [ key-name ]
#SET #HIGHPIN { OFF | ON }
#SET #HOME directory
#SET #IN file-name
#SET #INFORMAT { PLAIN | QUOTED | TACL }
#SET #INLINEECHO num
#SET #INLINEOUT num
#SET #INLINEPREFIX [ prefix ]
#SET #INLINETO [ variable-level ]
#SET #INPUTEOF num
#SET #INSPECT { OFF | ON | SAVEABEND }
#SET #MYTERM home-term
#SET #OUT file-name
#SET #OUTFORMAT { PLAIN | PRETTY | TACL }
#SET #PARAM [ param-name [ param-value ] ]
#SET #PMSEARCHLIST searchlist
#SET #PMSG num
#SET #PREFIX [ text ]
#SET #PROCESSFILESECURITY " security"
#SET #PROMPT num
#SET #REPLYPREFIX [ num]
#SET #SHIFTDEFAULT { DOWN | NOOP | UP }
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-15
S yn ta x S u m m ary
# D E L T A C o m m a n d S um m ary
Description
xA
Convert ASCII
y,xA
Beginning
xC
Character move
x:C
xD
Löschen
EIfile$
EOfile$
xFC
Lowercase lines
y,xFC
Lowercase characters
x@FC
Uppercase lines
y,x@FC
Uppercase characters
FEvar$
FFvar$
xFGvar$
y,xFGvar$
FL
FOvar$
Pop variable
FTvar$
xFTvar$
FUvar$
Push variable
xFUvar$
Gvar$
Whole buffer
Itext$
Insert text
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-16
S yn ta x S u m m ary
# D E L T A C o m m a n d S um m ary
Description
xI
Insert ASCII
y,xI
Insert y*ASCII
xJ
Jump characters
xK
Kill lines
y,xK
Kill characters
xL
Move by lines
Mvar$
Invoke macro
xP
Write lines
y,xP
Write characters
Qvar$
xStext$
Suche
x:Stext$
xT
Type lines
y,xT
Type characters
@Tvar$
:Ttext$
Type text
xUvar$
y,xUvar$
xV
View lines
x:V
xXvar$
y,xXvar$
xY
Read lines
x\
Put x in text
^\
Condition
:?
NOT condition
'
End condition
Move X into Y
Clear X and Y
Display X or Y,X
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-17
S yn ta x S u m m ary
# D E L T A C o m m a n d S um m ary
Description
<
Begin iteration
x<
Iterate x times
Exit iteration
>
End iteration
@>
Kommentar
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
A-18
Error Messages
TACL can generate several types of errors. Table 5-1 on page 5-21 lists the types of
TACL errors and a sample display, description, and typical action for each type of error.
The first subsection describes:
TACL Error Messages - the text and meaning of each TACL error message and
warning.
Finally, Table B-2 on page B-70 lists error numbers that can be obtained from function
calls, including a call to #ERRORNUMBERS. The explanations of those errors can be
found in the alphabetic listing.
Caution. TACL text messages might change at anytime. You should not write TACL macros or
routines that are dependent on the format of text messages.
ABENDED: $XX
CPU time: 0:00:00.018
Termination Info: 24
TACL fatal error: super-group privilege required
Cause. For a RUN command with the PORTTACL option, the user must have a 255
group ID.
Effect. The TACL process ABENDs (terminates abnormally).
Recovery. Use a LOGON with a user group ID of 255 and execute the RUN command
again.
E rror M e ssa ge s
T A C L E rror M essa ge s
Cause. Certain built-in functions that perform I/O, including (#)PUSH #IN, (#)PUSH
#OUT, and #REQUESTER, require block buffers. There are only four available. More
than four block buffers would have been needed to carry out the action you requested.
Effect. The requested operation is ignored.
Recovery. Perform a (#)POP #IN or #OUT or #REQUESTER /CLOSE/ operation as
necessary.
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-5
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-6
E rror M e ssa ge s
T A C L E rror M essa ge s
Recovery. Use #ERRORNUMBERS to see the subcode (nnn) that indicates the
specific cause of the error:
Subcode
Meaning
Indicates that flags.<10> = 1 and flags.<11:12> <> 0 and you are trying
to create a process on a remote system that is a NonStop 1+, or any
other NonStop system operating under operating system RVU B20 or
earlier; the use of DEFINEs is not allowed.
Adjust and retry the call to #NEWPROCESS. If errors recur, contact your service
provider.
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-8
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-9
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-12
E rror M e ssa ge s
T A C L E rror M essa ge s
Recovery. See the Guardian Procedure Errors and Messages Manual for corrective
action for the error number indicated by nnn.
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-14
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-15
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-16
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-17
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-18
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-19
E rror M e ssa ge s
T A C L E rror M essa ge s
*ERROR* No backup
Cause. You attempted to do a (#)SWITCH operation while your TACL had no backup
process.
Effect. The requested operation is ignored. Ensure that your TACL has a backup
before requesting a (#)SWITCH operation.
Recovery. Ensure that your TACL has a backup before requesting a (#)SWITCH
operation.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-20
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-21
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
Recovery. Check that you have correctly specified the variable type or I/O mode.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-23
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-24
E rror M e ssa ge s
T A C L E rror M essa ge s
Second Number
<n>
Third number
<d>
Fourth number
Recovery. Refer to the Guardian Procedure Errors and Messages Manual for a
description of PROCESS_GETINFO_ errors. The error information and the context in
which the error occurs may suggest a recovery action. If not, contact your service
provider.
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
Recovery. Use a FILLER byte to ensure proper alignment of a STRUCT item and
another item that redefines it.
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-28
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-31
E rror M e ssa ge s
T A C L E rror M essa ge s
Recovery. Decrease the size of macros or routines where possible, avoid excessive
nesting of macros or routines, and structure recursive macros so that they invoke
themselves in their last statements, so that each instance of the macro vanishes from
the text buffer before the next one begins. Use loops to perform operations on large
amounts of data a little at a time. Use options, such as LOADED in the LOAD
command, or other similar means, to direct results to variables. Use the VOLUME
command to reduce the number of template fields you need to pass to #FILENAMES.
E rror M e ssa ge s
T A C L E rror M essa ge s
The TACL IN file is read into the text buffer until any square brackets have been
balanced.
File or variable macros, when invoked, are read entirely into the text buffer; dummy
arguments are substituted as they are read in.
All other variable types, when invoked, are read entirely into the text buffer.
During execution, the space available in the text buffer diminishes as routines and
macros are nested. Also, TACL can use up to half of the available area of the text
buffer as a scratch area.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-33
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-34
E rror M e ssa ge s
T A C L E rror M essa ge s
S, P, E, and L are the TACL registers; CS is the code segment for the P register.
Additional information about trap errors and trap handling is given in the Guardian
Programmers Guide and the Guardian Procedure Calls Reference Manual.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-35
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-36
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-38
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-39
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-40
E rror M e ssa ge s
T A C L E rror M essa ge s
Cause. The CPRULES file version is no longer supported by this RVU of TACL.
Effect. The requested operation is ignored.
Recovery. See your service provider to obtain a new copy of the CPRULES file in
question.
E rror M e ssa ge s
T A C L E rror M essa ge s
E rror M e ssa ge s
T A C L E rror M essa ge s
Recovery. Refer to the Guardian Procedure Errors and Messages Manual for
recovery and file system error information.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-43
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-44
E rror M e ssa ge s
T A C L E rror M essa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-45
E rror M e ssa ge s
D E F IN E E rror M essa ge s
E rror M e ssa ge s
D E F IN E E rror M essa ge s
Recovery. Correct the working set, then retry the operation. See Table 8-7 on
page 8-185 for consistency rules.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-47
E rror M e ssa ge s
D E F IN E E rror M essa ge s
Effect.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-48
E rror M e ssa ge s
D E F IN E E rror M essa ge s
E rror M e ssa ge s
See the Guardian Procedure Errors and Messages Manual for a description of the
subcode, and of process creation error messages in general.
If the error is not in a defined category, TACL displays *ERROR* Subcode nnn.
The #ERRORNUMBERS built-in variable stores four space-separated numbers after a
process creation operation. The first of the four numbers returned, 1101, represents
the process creation error (if no error occurred, all four numbers are zero). The second
number identifies the specific error, as listed in Table B-1.
Table B-1. #ERRORNUMBERS Results (page 1 of 2)
Number
Error
Library conflict
10
E rror M e ssa ge s
Error
11
12
Program file and library file specified are the same file
13
14
15
If the second number is 3, 5, 8, 11, 13, 14, or 15, the third number contains a filesystem error number identifying the specific error condition.
If the second number is 6, the third number contains either 0, specifying that the
program file is in error, or 1, specifying that the library file is in error. The fourth number
contains a value in the range 1-14 that specifies why the file format is invalid. The
numbers correspond to the positions in the list of process creation illegal format error
messages given in the preceding list; for example, 3 indicates the main procedure is
missing.
Messages for H-series only. These are all designated by the prefix DUMP_.
Messages common to all systems, H-series, G-series and D-series. The wording
may differ slightly between systems.
DUMP_PARAM_CONFLICT
Cause. You specified both parallel and online options. This is not possible.
Effect. RCVDUMP does not continue processing.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-51
E rror M e ssa ge s
DUMP_INSUFFICIENT_PRIVILEGE
Cause. Receive dump was not started by super user id. Your current id cannot
perform this operation.
Effect.
DUMP_NOT_LOCAL
Cause. You cannot dump a remote system.
Effect. RCVDUMP does not continue processing.
Recovery. Run RCVDUMP on the remote system.
DUMP_SLICE_NOT_STOPPED
Cause. The PE on the slice you specified has not been stopped.
Effect. RCVDUMP does not continue processing.
Recovery. You must stop that PE or specify an alternative.
DUMP_CPU_NOT_HALTED
Cause. The logical cpu has not halted.
Effect. RCVDUMP does not continue processing.
Recovery. Either halt that cpu or specify another one.
DUMP_NO_DISK_SPACE
Cause. There is not enough space on the disk that contains your designated dump
file.
Effect. RCVDUMP does not continue processing.
Recovery. Select a dump file on another disk.
DUMP_PRIME_FAILED
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-52
E rror M e ssa ge s
DUMP_NO_MEMORY
Cause. Couldnt allocate memory for internal data buffers.
Effect.
Recovery.
DUMP_COMM_FAILURE
Cause. RCVDUMP couldnt talk to the downed CPU.
Effect.
Recovery.
DUMP_MEM_CONFIG_ERROR
Cause. Memory configuration check failed.
Effect.
Recovery.
DUMP_COMPRESSED_DATA_ERROR
Cause. Compressed data received from HSS is not correct.
Effect.
Recovery.
DUMP_INVALID_STARTER_PKT
Cause. Receive dump has received invalid starter packet from HSS.
Effect.
Recovery.
DUMP_PROCESS_CREATE_ERROR
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-53
E rror M e ssa ge s
Recovery.
DUMP_ONLINE_PROCESS_ABEND
Cause. Online dump process abended.
Effect.
Recovery.
DUMP_DUPLICATE_INVOCATION
Cause. Already one instance of receive dump is running on this logical CPU.
Effect.
DUMP_INTERNAL_ERROR
Cause. Internal error like disk file open failed or write to the disk file failed with any
error other than no disk space.
Effect.
Recovery.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-54
E rror M e ssa ge s
Cause. You attempted to dump a processor that had not been through the reset-load
sequence.
Effect. No processor is dumped.
Recovery. Do the reset-load and then retry the command.
INVALID dump-file-name.
Cause. You specified an invalid file name.
Effect. No processor is dumped.
Recovery. Specify a valid file name.
E rror M e ssa ge s
INVALID dump-file-name.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-56
E rror M e ssa ge s
MISSING dump-file-name.
Cause. You did not specify a dump file name.
Effect. No processor is dumped.
Recovery. Specify a file in the command.
MISSING cpu NUMBER.
Cause. You did not specify a processor to dump.
Effect. No processor is dumped.
Recovery. Specify a CPU number in the command.
UNABLE TO CREATE file-name, ERROR nnnn.
Cause. The specified file could not be created because file-system error nnnn
occurred.
Effect. No processor is dumped.
Recovery. Correct the cause of the file-system error and reenter the command.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-57
E rror M e ssa ge s
R E LO A D E rror M essa ge s
E rror M e ssa ge s
usually prevent RELOAD from going any farther. A third class of messages are
warnings, which dont indicate the failure of RELOAD of any CPU, but indicate
something amiss in the system.
E rror M e ssa ge s
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-60
E rror M e ssa ge s
Recovery. Make sure the alternate osdir file, its volume and its subvolume are
properly specified in the command line. If they are, see if the file is open, unreadable or
of the wrong type.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-61
E rror M e ssa ge s
CPU nn is illegal.
Cause. An invalid CPU number was specified.
Effect. The RELOAD operation aborts.
Recovery. Correct the CPU number and reissue the command.
E rror M e ssa ge s
Cause. An attempt was made to reload the indicated CPU, but the CPU was not
configured at system generation time.
Effect. CPU nn is not reloaded.
Recovery. Correct the CPU number and reissue the command.
20 to 29
Common logic for sending packets over the bus (either initial boots or
CPU image)
30 to 39
Setting breakpoints
80 to 99
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-63
E rror M e ssa ge s
20 to 29
Common logic for sending packets over the bus (either initial boots or
CPU image)
30 to 39
Setting breakpoints
80 to 99
20 to 29
Common logic for sending packets over the bus (either initial boots or
CPU image)
30 to 39
Setting breakpoints
80 to 99
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-64
E rror M e ssa ge s
20 to 29
Common logic for sending packets over the bus (either initial boots or
CPU image)
30 to 39
Setting breakpoints
80 to 99
20 to 29
Common logic for sending packets over the bus (initial boots or CPU
image)
30 to 39
Setting breakpoints
80 to 99
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-65
E rror M e ssa ge s
20 to 29
Common logic for sending packets over the bus (initial boots or CPU
image)
30 to 39
Setting breakpoints
80 to 99
XXXXXX: ignored
Cause. The indicated command was ignored.
Effect. What you typed (XXXXXX) is returned in uppercase along with the error.
Recovery. Correct and reissue the command.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-66
E rror M e ssa ge s
Invalid range.
Cause. The indicated CPU range was unacceptable.
Effect. The RELOAD command aborts.
Recovery. Correct and reissue the command.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-67
E rror M e ssa ge s
Effect. What you typed (XXXXXX) is returned in uppercase along with the error.
Recovery. Correct and reissue the command.
Operand error.
Cause. The operand was unacceptable.
Effect. The RELOAD command aborts.
Recovery. Correct and reissue the command.
Scanner error:nnn.
Cause. There was a scanner error scanning the command as indicated by the decimal
number nnn.
Effect. The RELOAD command aborts.
Recovery. Correct or simplify the command and reissue it.
Syntax error:
(command line)
^
Cause. There was a syntax error in the indicated command line at or before the point
shown by the arrow.
Effect. The command is ignored.
Recovery. Correct and reissue the command.
E rror M e ssa ge s
E M S M essa ge s
EMS Messages
These Event Management Service (EMS) messages can be generated by a TACL
process.
001
TACL DEVICE I/O ERROR: file-system-error, device-name
file-system-error
the I/O error.
device-name
the device name.
Cause. An I/O error occurred when a TACL process attempted to communicate with a
device. The message is generated only for the first occurrence of the error. For more
information about file-system error messages, see the Guardian Procedure Calls
Reference Manual and the Guardian Procedure Errors and Messages Manual.
This error is defined as ZTAC-EVT-IO-ERROR in the ZSPIDEF.ZTACDDL file.
Effect. Depends on the error.
Recovery. Depends on the error.
002
TACL BACKUP CREATE ERROR: process-create-error, error-detail
process-create-error
the process-creation error.
error-detail
the process-creation error detail.
Cause. A process creation error occurred when a TACL process attempted to create a
backup process. The message is generated only for the first occurrence of the error.
For more information about file-system error messages, see the Guardian Procedure
Calls Reference Manual and the Guardian Procedure Errors and Messages Manual.
This error is defined as ZTAC-EVT-CREATE-ERROR in the ZSPIDEF.ZTACDDL file.
Effect. Depends on the error.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-69
E rror M e ssa ge s
E rro r N um b ers
Error Numbers
Some TACL functions (#ERRORNUMBERS in particular) return an error number as
part of their result. Table B-1 on page B-50 lists the TACL error numbers and their
meanings. More complete descriptions of the errors can be found earlier in this section.
Numbers lower than 1024 are issued by the file system or the sequential I/O facility
(SIO) and are described elsewhere. If you receive an error greater than 1024 that is
not included in this table, call your service provider.
Table B-2. Error Numbers Associated With TACL Messages (page 1 of 5)
Error
Number
Error Text
1024
1025
1026
1027
1028
1029
1030
1031
No such variable
1032
1033
1034
1035
1036
1037
Arithmetic overflow
1038
1039
1040
1041
Disallowed by $CMON
1042
1043
Duplicate keyword
1044
1045
1046
1047
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-70
E rror M e ssa ge s
E rro r N um b ers
Error Text
1048
1049
1050
1051
1053
1054
1055
1056
Too long
1057
1058
1059
1060
1061
Not found
1062
Not in buffer
1063
1064
1065
1066
1067
No such line
1068
1069
1070
Level is in use
1071
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
E rror M e ssa ge s
E rro r N um b ers
Error Text
1084
1085
1086
1087
1088
1089
1090
Stack overflow
1091
1092
1093
1094
1095
1096
1097
1098
1099
1101
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
No backup
1121
1122
1123
E rror M e ssa ge s
E rro r N um b ers
Error Text
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1135
1136
1137
Illegal value
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
Expecting |DO|
1156
Expecting |UNTIL|
1157
1158
E rror M e ssa ge s
E rro r N um b ers
Error Text
1159
1160
1161
1162
1163
1164
1165
1166
Record size cannot exceed 1024 bytes for unstructured non-edit files
1167
1168
2059
2060
No more DEFINEs
2061
No more attributes
2062
2064
2066
2067
2068
2069
2073
2074
2049
2050
2051
2052
2053
2054
2055
2056
Attribute missing
2057
2058
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
B-74
C
Mapping TACL Built-In Functions to
Guardian Procedures
Many TACL built-in functions access Guardian procedures to provide functionality.
Table C-1 lists the TACL built-in functions and specifies whether each TACL built-in
function accesses a Guardian procedure, and if so, which procedure or procedures.
Table C-1. TACL Built-In Functions and Guardian Procedures (page 1 of 7)
TACL Built-In
Guardian Procedure
#ABEND
PROCESS_STOP_
#ABORTTRANSACTION
ABORTTRANSACTION
#ACTIVATEPROCESS
PROCESS_ACTIVATE_
#ADDDSTTRANSITION
ADDDSTTRANSITION
#ALTERPRIORITY
PROCESS_SETINFO_
#APPEND
None
#APPENDV
None
#ARGUMENT
None
#BACKUPCPU
PROCESS_GETINFO_,
PROCESSHANDLE_DECOMPOSE_
#BEGINTRANSACTION
BEGINTRANSACTION
#BREAKPOINT
None
#BUILTINS
None
#CASE
None
#CHANGEUSER
PROCESSACCESSID
#CHARADDR
None
#CHARBREAK
None
#CHARCOUNT
None
#CHARDEL
None
#CHARFIND
None
#CHARFINDR
None
#CHARFINDRV
None
#CHARFINDV
None
#CHARGET
None
#CHARGETV
None
#CHARINS
None
#CHARINSV
None
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-1
Guardian Procedure
#COLDLOADTACL
None
#COMPAREV
None
#COMPUTE
None
#COMPUTEJULIANDAYNO
COMPUTEJULIANDAYNO
#COMPUTETIMESTAMP
COMPUTETIMESTAMP
#COMPUTETRANSID
COMPUTETRANSID API
#CONTIME
#CONVERTPHANDLE
PROCESSHANDLE_TO_STRING_
#CONVERTPROCESSTIME
CONVERTPROCESSTIME
#PROCESSINFO
FILENAME_DECOMPOSE_,
PROCESSHANDLE_DECOMPOSE_,
PROCESS_GETPAIRINFO_, PROCESS_GETINFOLIST_,
PROCESS_GETINFO_,
PROCESSHANDLE_TO_STRING_, FILENAME_EDIT_,
FILENAME_DECOMPOSE_
#CONVERTTIMESTAMP
CONVERTTIMESTAMP
#CREATEFILE
FILE_CREATELIST_, FILENAME_DECOMPOSE_
#CREATEPROCESSNAME
CREATEPROCESSNAME
#CREATEREMOTENAME
CREATEREMOTENAME
#DEBUGPROCESS
PROCESS_DEBUG_
#DEF
None
#DEFINEADD
DEFINEADD
#DEFINEDELETE
DEFINEDELETE
#DEFINEDELETEALL
DEFINEDELETEALL
#DEFINEINFO
DEFINEINFO
#DEFINENAMES
GETSYSTEMNAME, DEFINENEXTNAME
#DEFINENEXTNAME
DEFINENEXTNAME
#DEFINEREADATTR
DEFINEREADATTR
#DEFINERESTORE
DEFINERESTORE
#DEFINERESTOREWORK
DEFINERESTOREWORK
#DEFINESAVE
DEFINESAVE
#DEFINESAVEWORK
DEFINESAVEWORK
#DEFINESETATTR
DEFINESETATTR
#DEFINESETLIKE
DEFINESETLIKE
#DEFINEVALIDATEWORK
DEFINEVALIDATEWORK
#DELAY
SIGNALTIMEOUT, AWAITIO
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-2
Guardian Procedure
#DELTA
None
#DEVICEINFO
FILE_GETINFOLISTBYNAME_
#EMPTY
None
#EMPTYV
None
#EMSADDSUBJECT
#EMSADDSUBJECTV
#EMSGET
#EMSGETV
#EMSINIT
None
#EMSINITV
None
#EMSTEXT
#EMSTEXTV
#ENDTRANSACTION
ENDTRANSACTION API
#EOF
None
#ERRORTEXT
None
#EXCEPTION
None
#EXTRACT
None
#EXTRACTV
None
#FILEGETLOCKINFO
FILE_GETLOCKINFO_
#FILEINFO
#FILENAMES
None
#FILTER
None
#FRAME
None
#GETCONFIGURATION
None
#GETPROCESSSTATE
PROCESS_GETINFOLIST_
#GETSCAN
None
#HISTORY
None
#IF
None
#INITTERM
None
#INLINEEOF
None
#INPUT
None
#INPUTV
None
#INTERACTIVE
FNAMECOMPARE
#INTERPRETJULIANDAYNO
INTERPRETJULIANDAYNO
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-3
Guardian Procedure
#INTERPRETTIMESTAMP
INTERPRETTIMESTAMP
#INTERPRETTRANSID
#JULIANTIMESTAMP
JULIANTIMESTAMP
#KEEP
None
#KEYS
None
#LINEADDR
None
#LINEBREAK
None
#LINECOUNT
None
#LINEDEL
None
#LINEFIND
None
#LINEFINDR
None
#LINEFINDRV
None
#LINEFINDV
None
#LINEGET
None
#LINEGETV
None
#LINEINS
None
#LINEINSV
None
#LINEJOIN
None
#LOAD
None
#LOCKINFO
PROCESSHANDLE_TO_FILENAME_,
FILENAME_TO_OLDFILENAME_, LOCKINFO
#LOGOFF
None
#LOOKUPPROCESS
PROCESSHANDLE_DECOMPOSE_,
FILENAME_DECOMPOSE_, PROCESS_GETPAIRINFO_,
GETSYSTEMNAME,
#LOOP
None
#MATCH
None
#MOM
PROCESS_GETINFO_
#MORE
None
#MYGMOM
PROCESS_GETINFO_
#MYPID
PROCESSHANDLE_DECOMPOSE_
#MYSYSTEM
MYSYSTEMNUMBER
#NEWPROCESS
FILENAME_DECOMPOSE_, PROCESS_GETINFO_,
OLDFILENAME_TO_FILENAME_, PROCESS_CREATE_,
PROCESSHANDLE_TO_STRING_, FILE_OPEN_,
FILE_CLOSE_
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-4
Guardian Procedure
#NEXTFILENAME
NEXTFILENAME, FNAMECOLLAPSE
#OPENINFO
FILENAME_DECOMPOSE_, FILE_GETOPENINFO_,
FILENAME_UNRESOLVE_
#OUTPUT
None
#OUTPUTV
None
#PAUSE
#POP
None
#PROCESS
MYSYSTEMNUMBER,
PROCESSHANDLE_DECOMPOSE_,
PROCESSHANDLE_TO_STRING_
#PROCESSEXISTS
None
#PROCESSINFO
PROCESS_GETPAIRINFO_, PROCESS_GETINFOLIST_ ,
PROCESS_GETINFO_ ,
PROCESSHANDLE_TO_STRING_ ,
FILENAME_DECOMPOSE_, FILENAME_EDIT_,
PROCESSHANDLE_DECOMPOSE_
#PROCESSORSTATUS
PROCESSORSTATUS, REMOTEPROCESSORSTATUS
#PROCESSORTYPE
PROCESSOR_GETNAME_ ,
PROCESSHANDLE_DECOMPOSE_
#PURGE
PURGE, FILEINFO
#PUSH
None
#RAISE
None
#RENAME
#REPLY
None
#REPLYV
None
#REQUESTER
DEVICEINFO2, OLDFILENAME_TO_FILENAME_,
FILENAME_COMPARE_, FILEINFO
#RESET
None
#REST
None
#RESULT
None
#RETURN
None
#ROUTINENAME
None
#SEGMENT
None
#SEGMENTCONVERT
None
#SEGMENTINFO
None
#SEGMENTVERSION
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-5
Guardian Procedure
#SERVER
FILENAME_TO_OLDFILENAME_
#SET
None
#SETBYTES
None
#SETCONFIGURATION
PROCESSACCESSID, FILE_GETINFOBYNAME_,
FILE_OPEN_, FILE_CLOSE_, READX, POSITION,
WRITEX
#SETMANY
None
#SETPROCESSSTATE
PROCESS_SETINFO_
#SETSCAN
None
#SETSYSTEMCLOCK
SETSYSTEMCLOCK
#SETV
None
#SHIFTSTRING
SHIFTSTRING
#SORT
No GPC Used
#SPIFORMATCLOSE
#SSGET
#SSGETV
#SSINIT
#SSMOVE
#SSNULL
#SSPUT
#SSPUTV
#STOP
PROCESS_STOP_, PROCESS_GETPAIRINFO_
#SUSPENDPROCESS
PROCESS_SUSPEND_
#SWITCH
PROCESS_STOP_, CHECKPOINT
#SYSTEM
None
#SYSTEMNAME
GETSYSTEMNAME
#SYSTEMNUMBER
LOCATESYSTEM
#TACLOPERATION
None
#TACLVERSION
None
#TIMESTAMP
None
#TOSVERSION
TOSVERSION
#UNFRAME
None
#USERID
None
#USERNAME
None
#VARIABLEINFO
None
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-6
Guardian Procedure
#VARIABLES
No GPC Used.
#VARIABLESV
No GPC Used.
#WAIT
No GPC Used.
#XFILEINFO
FILE_GETINFOLISTBYNAME_,
OLDFILENAME_TO_FILENAME_ ,
FILENAME_DECOMPOSE_
#XFILENAMES
No GPC Used.
#XFILES
No GPC Used.
#XLOGON
PROCESSACCESSID, USER_AUTHENTICATE_
#XPPD
PROCESS_GETPAIRINFO_, MYSYSTEMNUMBER,
PROCESSHANDLE_DECOMPOSE_,
FILENAME_DECOMPOSE_
#XSTATUS
PROCESS_GETINFO_, PROCESS_GETPAIRINFO_,
PROCESS_GETINFOLIST_, PROCESS_STOP_, UNUMZ,
SHIFTSTRING, GETSYSTEMNAME,
PROCESSHANDLE_DECOMPOSE_
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-7
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
C-8
Glossary
access mode. A file attribute that determines what operations you can perform on the file,
like reading and writing.
alias. An alternative name for a given function.
ancestor. The process that is notified when a named process or process pair is deleted.
The ancestor is usually the process that created the named process or process pair.
argument. A parameter that you specify when you invoke a macro or routine.
array data item. A portion of a STRUCT that is treated as an array; that is, you can refer to
the whole item, or you can refer to individual elements of it.
ASSIGN. An association of a physical file name with a logical file name made by the TACL
ASSIGN command. The physical file name is any valid file name. The logical file name
is used within a program. The ASSIGN is therefore used to pass file names to
programs.
Blade Element. See slice. Also known as a NonStop Blade Element.
BREAK mode. A mode of process execution where a process gains exclusive access to a
terminal when the BREAK key is pressed. BREAK mode is established using
SETPARAM function 3 or SETMODE function 11.
BREAK owner. The process that receives the break-on-device message when the BREAK
key is pressed. The establishment of BREAK ownership is achieved using SETPARAM
function 3 or SETMODE function 11.
breakpoint. A location (or point) in a program where execution is to be suspended so that
you can then examine and perhaps modify the state of the program. You can set and
clear breakpoints with _DEBUGGER commands.
built-in. A function or variable built into TACL; a built-in cannot be modified. Other variables
can be modified by the user.
C-series system. A system that is running a C-series RVU.
CAID. See creator access ID (CAID).
child process. A process created by the current process.
code segment. An area of memory that contains program instructions to be executed, plus
related information. An absolute segment whose logical pages are read from but never
written back to the swap file. command. A text string that directs the computer to
perform a task. Commands are usually composed of a verb that tells the computer
what to do and an object or list of objects that is acted on by the verb. TACL
commands are interpreted by TACL and are extensible.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-1
G lo ssary
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-2
G lo ssary
device subtype. A value that further qualifies a device type. For example, a device type of
4 indicates a magnetic tape drive; if the same device has a device subtype of 2, then
the magnetic tape drive has a 3206 controller.
disk volume. Also called a disk or a volume; a magnetic storage medium. Disk names
consist of a dollar sign ($) followed by one to seven alphanumeric characters (network)
or one to eight alphanumeric characters (local), the first of which must be alphabetic.
EDIT file. . A file in a format defined by the EDIT product.
enclosure. A unit composed of one or more labels, such as |THEN| or |DO|, and the text
associated with each label. Enclosures are found only in the TACL built-in functions
#DEF, #IF, #CASE, and #LOOP, which are enclosed in brackets to provide boundaries
for their enclosures. TACL defers execution of text that is associated with labels until it
determines the correct label to use.
Enscribe. A database record management system.
exception. An unusual event that causes TACL to interrupt the normal flow of invocations
and transfer to special code. (See exception handler.) This unusual event could be
BREAK, a TACL error, or a user-defined exception.
exception handler. A series of TACL statements that perform resource deallocation and
cleanup after an exception.
exclusion mode. The attribute of a lock that determines whether any process except the
lock holder can access the locked data.
expand. A type of invocation. (See invoke.) To expand a variable, specify the variable
name in brackets; TACL returns the expansion in place of the variable name.
expression. A text, string, or integer constant, a variable, or a value obtained by combining
constants, variables, and other expressions with operators. Expressions are used as
arguments to commands and built-in functions.
extended data segment. One or more consecutive absolute segments that are
dynamically allocated by a process.
extensible data segment. An extended data segment for which swap file extents are not
allocated until needed.
extent. A contiguous area of a disk allocated to the same file.
fault tolerance. The ability of a computer system to continue operating during and after a
fault (the failure of a system component).
file code. An integer value assigned to a file for application-dependent purposes.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-3
G lo ssary
file lock.
file lock. A mechanism that restricts access to a file by all processes except the lock
owner.
file. As used here, a file refers to an organized collection of data stored on a disk. In
general, a file can be a disk file, a process, or a device.
file name. A unique name for a file. This name is used to open a file and thereby provides
a connection between the opening process and the file. File names consist of one to
eight alphanumeric characters, the first of which must be alphabetic. file name
template. A sequence of characters including the asterisk (*) and question mark (?)
that matches existing file names by expanding each asterisk to zero or more letters,
digits, dollar signs ($), and pound signs (#) and replacing each question mark with
exactly one letter, digit, dollar sign, or pound sign.
file system. A set of operating system procedures and data structures that provides for
communication between a process and a file, which can be a disk file, a device other
than a disk, or another process.
FILLER byte. A portion of a STRUCT that is used only to maintain the alignment of
adjacent STRUCT items.
frame. A local environment managed by the #FRAME, #UNFRAME, and #RESET built-in
functions.
fully qualified file name. The complete name of a file, including the node name. For
permanent disk files, this file name consists of a node name, volume name, subvolume
name, and file ID. For temporary disk files, the file name consists of a node name, a
subvolume name, and a temporary file ID. For a device, the file name consists of a
node name and a device name or logical device number. For a named process, the file
name consists of a node name, and a process name. For an unnamed process, the file
name consists of a node name, CPU number, PIN, and sequence number. Contrast
with partially qualified file name.
function. An operation or set of operations that is invoked by the appearance of the
function name and its arguments at the point where the result of the function is wanted.
A built-in function is hard coded into TACL; users can define other functions. Variable
types for functions include TEXT, MACRO, and ROUTINE.
GMT. See Greenwich mean time (GMT).
godmother. See job ancestor.
Greenwich mean time (GMT). The mean solar time for the meridian at Greenwich,
England.
Gregorian date. A date specified according to the common calendar using the month of
the year (January through December), the day of the month, and the year A.D.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-4
G lo ssary
ho m e term ina l.
home terminal. The terminal whose name is returned by a call to the MYTERM procedure,
or the name returned in the hometerm parameter of the PROCESS_GETINFO_
procedure. The home terminal is often the terminal from which the process or
processs ancestor was started.
interprocess communication (IPC). The exchange of messages between processes in a
system or network. interrupt. The mechanism by which a processor module is notified
of an asynchronous event that requires immediate processing.
invoke. A request to execute TACL code. To invoke a variable, (1) list its name (like an
implied RUN statement) without regard to results or (2) surround the variable name in
square brackets ([]) to replace the name with its expansion (text or macro variable) or
results (routine).
IPC. See interprocess communication (IPC).
job ancestor. A process that is notified when a process that is part of a job is deleted. The
job ancestor of a process is the process that created the job to which the process
belongs.
Julian timestamp. The number of microseconds since midnight January 1, 4713 B.C. at
the Greenwich meridian.
LCT. See local civil time (LCT).
LDEV. See logical device (LDEV).
level. One element of the set of values stored in a stack and known as a variable.
local civil time (LCT). Wall-clock time in the current time zone, including any
compensation for daylight-saving time.
local standard time (LST). The time of day in the local time zone excluding any
compensation made for daylight-saving time.
logical device (LDEV). (1) An addressable device, independent of its physical
environment. Portions of the same logical device can be located in different physical
devices, or several logical devices or parts of logical devices can be located in one
physical device. (2) A process that can be accessed as if it were an I/O device; for
example, the operator process is logical device LDEVOPR.
logical device number. A number that identifies a configured logical device. A logical
device number can be used instead of a device file name when opening a device file.
logical processor. The combination of equivalent processor elements in the processor
slices that are running in the same instruction stream in loose lock-step.
LST. See local standard time (LST).
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-5
G lo ssary
m acro .
macro. A named sequence of one or more instructions invoked by the appearance of the
macro name. When a macro is invoked, TACL replaces arguments of the form %n%
with actual arguments passed to it and returns, as a result, the instructions that define
the macro, including argument values.
message system. A set of operating system procedures and data structures that handles
the mechanics of exchanging messages between processes.
metacharacter. A character that directs TACL to evaluate subsequent text in a special way.
mom. A process that is notified when certain other processes are deleted. When a process
is part of a process pair, the mom of the process is the other member of the pair. When
a process is unnamed, its mom is usually the process that created it. monitor. A
process that, among other functions, is responsible for checking that certain other
processes continue to run. If a process should stop, it is the monitors responsibility to
restart it.
multibyte character set. A means for identifying written characters for national languages
that require more than one byte to represent a single character.
named process. A process to which a process name was assigned when the process was
created. Contrast with unnamed process.
node. A system of one or more processor modules. Typically, a node is linked with other
nodes to form a network.
node name. The portion of a file name that identifies the system through which the file can
be accessed.
nonretryable error. An error condition returned by the file system that cannot be recovered
by retrying the operation even after operator intervention. Contrast with retryable error.
NonStop Advanced Architecture. The H-series architecture that allows up to three levels
of redundancy. Logical processors consist of one to three physical processors known
as processor elements (PEs). The logical processor is equivalent to the term CPU. For
availability issues, the processor elements are all located on different circuit boards.
These boards are known as blade elements (or slices) and are identified by the letters
A, B, or C.
NonStop Blade Element. See slice. Also known as Blade Element.
NonStop SQL/MP. A relational database management system that provides efficient online
access to large distributed databases.
nowait I/O. An operation with an I/O device where the process does not wait for the I/O
operation to finish. Contrast with waited I/O.
NSAA. See NonStop Advanced Architecture.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-6
G lo ssary
o ne -w a y co m m u nication .
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-7
G lo ssary
p ro ce ss a ccess ID (P A ID ).
process access ID (PAID). A user ID used to determine whether a process can make
requests to the system; for example, to open a file, stop another process, and so on.
The process access ID is usually the same as the creator access ID, but it can be
different; the owner of the corresponding object file can set the object file security such
that it runs with a process access ID equal to the user ID of the file owner, rather than
the creator of the process. Contrast with creator access ID.
process file name. A file name that identifies a process.
process file segment (PFS). An extended data segment that is automatically allocated to
every process and contains operating system data structures, file-system data
structures, and memory-management pool data structures.
process ID. A C-series structure that serves as an address of a process.
process identification number (PIN). An unsigned integer that identifies a process in a
processor module.
process name. A name that can be assigned to a process when the process is created. A
process name uniquely identifies a process or process pair in a system. A process
name consists of a dollar sign ($), followed by one to five alphanumeric characters, the
first of which must be alphabetic.
process pair. Two processes created from the same object file running in a way that
makes one process a backup process of the other in case of failure. Periodic
checkpointing ensures that the backup process is always ready to take over from the
primary if the primary process should fail. The process pair has one process name, but
each process has a different process identification number (PIN).
process qualifier. A suffix to a process file name that gets passed to a process when the
process is opened; its use is application-dependent.
process time. The amount of time a process has been active while the processor module
was in the environment of the process.
processor clock. A hardware timer on each processor module that keeps processor time;
the number of microseconds since cold load.
processor time. The time represented by a processor clock.
program. A sequence of instructions and data. In TACL, variables of type TEXT, MACRO,
and ROUTINE can define programs.
real time. See wall-clock time.
record lock. A lock held by a process or a transaction that restricts access to that record
by other processes.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-8
G lo ssary
red efinition .
redefinition. A STRUCT declaration that gives a new definition, such as a different data
type or a different alignment, to an existing STRUCT or STRUCT item. All definitions
are valid concurrently, allowing a STRUCT or STRUCT item to be used in a variety of
ways.
reply. A response to a requester process by a server process. Contrast with request.
request. A message formatted and sent to a server by a requester. Requests also include
status messages such as CPU up and CPU down messages, which are placed on the
intended recipients process message queue ($RECEIVE file) by the operating system.
Contrast with reply.
requester. A process that initiates interprocess communication by sending a request to
another process. Contrast with server.
response. See reply.
retryable error. An error condition returned by the file system that can be corrected by
repeating the operation that caused the error. Sometimes operator intervention is
required before the retry; for example, to put paper into an empty printer. Contrast with
nonretryable error.
secondary extent. A contiguous area of disk storage allocated to a file. A file is made up of
one or more extents; the first extent is the primary extent, and other extents are
secondary extents. The secondary extents are all the same size for a specific file; the
primary extent can be a different size. See also primary extent.
segment. A unit of storage consisting of up to 64 pages of 1,024 words each.
segment file. As used by TACL, a file accessible by TACL that can contain TACL code and
data.
server. The process that receives, acts upon, and replies to messages from requesters.
Contrast with requester.
shared data segment. An extended data segment that can be accessed by more than one
process.
simple data item. A STRUCT item that contains a single value of a specific type.
slice. A portion of one or more logical processors and one part of a processor complex. A
slice consists of a chassis, processor board containing one or more processor
elements and memory, I/O interface board, midplane, optics adapters, fans, and power
supplies. Also called a processor slice. Also known as a blade element.
space-separated list. A list whose entries are separated from each other by a space.
Several built-in functions accept space-separated lists of values.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-9
G lo ssary
startu p seq u en ce .
startup sequence. A convention for sending and receiving certain messages while starting
a new process. By convention, the new process receives an Open message, followed
by a startup message, an assign message for each ASSIGN in effect, a param
message if there are any PARAMs in effect, and then a Close message string. A type
of argument that some commands and functions accept in place of a variable. A string
can be the name of a variable, text enclosed in quotation marks, or a concatenation of
such entities. The concatenation operator is '+' (the single quotes are part of the
operator). Under control of the QUOTED input format, a quoted string can contain
TACL metacharacters.
STRUCT. A variable that is structured into individual components that can be accessed
individually. Items within a STRUCT can be simple data items, arrays (which can be
further broken down into individual elements), or substructures.
STRUCT item. An element of a structure that can be individually accessed by a name of
the form structure-name:item-name.
substructure. A STRUCT item that is itself a STRUCT.
subvolume. A group of files stored on disk. These files all have the same subvolume
name, but each has a different file ID. A subvolume name consist of one to eight
alphanumeric characters, the first of which must be alphabetic. An example of a
subvolume name is $DATA.INFO. An example of a file name in this subvolume is
$DATA.INFO.RESULTS.
swapping. The process of copying information between physical memory and disk storage.
system process. A process whose primary purpose is to manage system resources rather
than to solve a users problem. A system process is essential to a system-provided
service. Failure of a system process often causes the processor module to fail. Most
system processes are automatically created when the processor module is cold
loaded. Contrast with user process.
system time. The time represented by any synchronized processor clock in the system.
template. A string of characters, including the special characters * and ?, used to match
another string of characters. Templates can be used in place of file names and
DEFINE names in some commands and built-in functions.
temporary disk file. A file stored on disk that will be purged automatically as soon as the
process that created it stops.
terminal-simulation process. A process that is made to behave like a terminal file.
text. A set of characters from the ISO 8859.1 character set. The length of text can be
limited by a specific function or command. TACL interprets a text argument as all
remaining text on the line, with leading and trailing spaces and end-of-line characters
removed.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-10
G lo ssary
timekeeping. A function performed by the operating system that involves initializing and
maintaining the correct time in a processor module.
timestamp. An item containing a representation of the time. A timestamp can be applied to
an object at a critical point, such as the last modification time of a file. transaction
identifier. A four-word identifier that uniquely identifies a transaction within the
Transaction Management Facility (TMF) subsystem.
TMF. See Transaction Management Facility (TMF).
Transaction Management Facility (TMF). HP software that provides transaction protection
and database consistency in demanding online transaction processing (OLTP) and
decision-support environments. It gives full protection to transactions that access
distributed SQL and Enscribe databases, as well as recovery capabilities for
transactions, online disk volumes, and entire databases.
transfer mode. The protocol by which data is transferred between a terminal and the
computer system. See conversational mode and page mode.
two-way communication. A form of interprocess communication in which the sender of a
message (requester process) expects data in the reply from the receiver (server
process). Contrast with one-way communication.
unnamed process. A process to which a process name was not assigned when the
process was created. Contrast with named process.
user ID. A unique pair of numbers that identify a user. A user ID has the form groupid,user-id, where the group-id identifies the users group, and user-id identifies the user
within the group.
user process. A process whose primary purpose is to solve a users problem. A user
process is not essential to the availability of a processor module and is created only
when the user explicitly creates it. Contrast with system process.
variable. A named quantity that can assume any of a given set of values.
variable level. A portion of a variable that can be individually addressed. New levels can
be added to the top of a variable stack, pushing down earlier levels, and can be
popped off the top of the stack. When the last level is popped, the variable ceases to
exist. For simplicity, variable levels are referred to as variables in many descriptions in
this manual.
variable line. A portion of a variable level that ends with a binary zero (an internal end-ofline character). Lines can be removed from the beginning of a variable level with the
#EXTRACT and #EXTRACTV functions and can be added to the end of a variable
level with the #APPEND and #APPENDV function.
variable type. The designation (MACRO, DELTA, STRUCT, TEXT, and so on) of a variable
level that describes its contents and the use for which it is designated.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-11
G lo ssary
virtua l m e m o ry.
virtual memory. A range of addresses that processes use to reference real storage, where
real storage consists of physical memory and disk storage.
volume. A disk drive or a pair of disk drives that forms a mirrored disk.
waited I/O. An operation with an I/O device where the process waits until the operation
finishes. Contrast with nowait I/O.
waiting process. A process that cannot execute until an event occurs, a resource
becomes available, or an interval of time passes.
wall-clock time. The local time of day, including any adjustment for daylight-saving time.
working set. A collection of DEFINE attributes that have been assigned values.
$CMON. See command-interpreter monitor ($CMON).
$RECEIVE. A special file name through which a process receives messages from other
processes.
H P N on S to p T A C L R e fe re nce M a n ua l 4 29 5 13 -0 1 7
Glossary-12
Index
A
Access a variable 4-5
ACTIVATE command 8-8
ADD DEFINE command 8-9
Add new users 8-14
ADDDSTTRANSITION command 8-12
ADDUSER program 8-14
ALARMOFF program 8-16
ALIAS 4-6
Alias variable 4-6
Allocate a variable 4-3
ALTER DEFINE command 8-17
Alter process priority 8-20
Alter status of bus 8-32
Alter status of ServerNet fabric 8-32
ALTPRI command 8-20
Ampersand 2-6
Arithmetic operators 3-1
Array data item 4-18
ASSIGN command 8-21
Assign logical file name 8-21
ATTACHSEG command 8-26
B
Background TACL process 6-11
Backup TACL process 8-28
BACKUPCPU command 8-28
BOOL data type 4-15
BREAK command 8-30
BREAK key 6-7
Breakpoint setting 8-30
BUILTINS command 8-31
Built-in functions
description of 7-2
#ABEND 9-12
#ABORTTRANSACTION 9-14
#ACTIVATEPROCESS 9-15
#ADDDSTTRANSITION 9-16
#ALTERPRIORITY 9-18
#APPEND 9-19
#APPENDV 9-20
#ARGUMENT 9-21
#BACKUPCPU 9-34
#BEGINTRANSACTION 9-35
#BREAKPOINT 9-37
#BUILTINS 9-38
#CASE 9-39
#CHANGEUSER 9-41
#CHARADDR 9-46
#CHARBREAK 9-47
#CHARCOUNT 9-49
#CHARDEL 9-51
#CHARFIND 9-53
#CHARFINDR 9-55
#CHARFINDRV 9-57
#CHARFINDV 9-59
#CHARGET 9-61
#CHARGETV 9-63
#CHARINS 9-65
#CHARINSV 9-67
#COLDLOADTACL 9-69
#COMPAREV 9-70
#COMPUTE 9-71
#COMPUTEJULIANDAYNO 9-72
#COMPUTETIMESTAMP 9-73
#COMPUTETRANSID 9-74
#CONTIME 9-75
#CONVERTPHANDLE 9-76
#CONVERTPROCESSTIME 9-78
#CONVERTTIMESTAMP 9-79
#CREATEFILE 9-81
#CREATEPROCESSNAME 9-83
#CREATEREMOTENAME 9-84
#DEBUGPROCESS 9-85
#DEF 9-87
Index
#DEFINEADD 9-92
#DEFINEDELETE 9-93
#DEFINEDELETEALL 9-94
#DEFINEINFO 9-95
#DEFINENAMES 9-97
#DEFINENEXTNAME 9-98
#DEFINEREADATTR 9-99
#DEFINERESTORE 9-101
#DEFINERESTOREWORK 9-103
#DEFINESAVE 9-104
#DEFINESAVEWORK 9-106
#DEFINESETATTR 9-107
#DEFINESETLIKE 9-108
#DEFINEVALIDATEWORK 9-109
#DELAY 9-110
#DELTA 9-111
#DEVICEINFO 9-134
#EMPTY 9-135
#EMPTYV 9-136
#EMSADDSUBJECT 9-137
#EMSADDSUBJECTV 9-139
#EMSGET 9-141
#EMSGETV 9-146
#EMSINIT 9-150
#EMSINITV 9-152
#EMSTEXT 9-154
#EMSTEXTV 9-156
#ENDTRANSACTION 9-158
#EOF 9-159
#ERRORTEXT 9-162
#EXCEPTION 9-163
#EXTRACT 9-165
#EXTRACTV 9-166
#FILEGETLOCKINFO 9-167
#FILEINFO 9-170
#FILENAMES 9-176
#FILTER 9-178
#FRAME 9-180
#GETCONFIGURATION 9-181
#GETPROCESSSTATE 9-184
#GETSCAN 9-187
#HISTORY 9-190
#IF 9-192
#INITTERM 9-199
#INLINEEOF 9-201
#INPUT 9-207
#INPUTV 9-211
#INTERACTIVE 9-215
#INTERPRETJULIANDAYNO 9-216
#INTERPRETTIMESTAMP 9-217
#INTERPRETTRANSID 9-218
#JULIANTIMESTAMP 9-219
#KEEP 9-220
#KEYS 9-221
#LINEADDR 9-222
#LINEBREAK 9-223
#LINECOUNT 9-225
#LINEDEL 9-226
#LINEFIND 9-228
#LINEFINDR 9-230
#LINEFINDRV 9-232
#LINEFINDV 9-234
#LINEGET 9-236
#LINEGETV 9-238
#LINEINS 9-240
#LINEINSV 9-242
#LINEJOIN 9-244
#LOAD 9-245
#LOCKINFO 9-248
#LOGOFF 9-252
#LOOKUPPROCESS 9-254
#LOOP 9-256
#MATCH 9-257
#MOM 9-258
#MORE 9-259
#MYGMOM 9-260
#MYPID 9-261
#MYSYSTEM 9-262
Index
#NEWPROCESS 9-265
#NEXTFILENAME 9-268
#OPENINFO 9-269
#OUTPUT 9-276
#OUTPUTV 9-279
#PAUSE 9-284
#PROCESS 9-290
#PROCESSEXISTS 9-291
#PROCESSINFO 9-294
#PROCESSLAUNCH 9-306
#PROCESSORSTATUS 9-308
#PROCESSORTYPE 9-309
#PUSH 9-313
#RAISE 9-314
#RENAME 9-315
#REPLY 9-316
#REPLYV 9-318
#REQUESTER 9-319
#RESET 9-324
#REST 9-325
#RESULT 9-326
#RETURN 9-327
#ROUTINENAME 9-331
#SEGMENT 9-332
#SEGMENTCONVERT 9-333
#SEGMENTINFO 9-335
#SEGMENTVERSION 9-337
#SERVER 9-338
#SET 9-342
#SETBYTES 9-345
#SETCONFIGURATION 9-346
#SETMANY 9-352
#SETPROCESSSTATE 9-354
#SETSCAN 9-357
#SETSYSTEMCLOCK 9-358
#SETV 9-360
#SHIFTSTRING 9-363
#SORT 9-365
#SPIFORMATCLOSE 9-367
#SSGET 9-368
#SSGETV 9-373
#SSINIT 9-377
#SSMOVE 9-379
#SSNULL 9-382
#SSPUT 9-383
#SSPUTV 9-388
#STOP 9-391
#SUSPENDPROCESS 9-393
#SWITCH 9-394
#SYSTEM 9-395
#SYSTEMNAME 9-396
#SYSTEMNUMBER 9-397
#TACLOPERATION 9-398
#TACLVERSION 9-401
#TIMESTAMP 9-403
#TOSVERSION 9-404
#UNFRAME 9-406
#USERID 9-408
#USERNAME 9-409
#VARIABLEINFO 9-410
#VARIABLES 9-413
#VARIABLESV 9-414
#WAIT 9-415
#XFILEINFO 9-419
#XFILENAMES 9-419
#XFILES 9-419
#XLOADEDFILES 9-419
#XLOGON 9-419
#XPPD 9-419
#XSTATUS 9-419
Built-in variables
description 7-3
#ASSIGN 9-31
#BREAKMODE 9-36
#CHARACTERRULES 9-44
#DEFAULTS 9-90
#DEFINEMODE 9-96
#ERRORNUMBERS 9-160
Index
#EXIT 9-164
#HELPKEY 9-188
#HIGHPIN 9-189
#HOME 9-191
#IN 9-194
#INFORMAT 9-196
#INLINEECHO 9-200
#INLINEOUT 9-202
#INLINEPREFIX 9-203
#INLINEPROCESS 9-204
#INLINETO 9-206
#INPUTEOF 9-210
#INSPECT 9-213
#MYTERM 9-263
#OUT 9-272
#OUTFORMAT 9-274
#PARAM 9-282
#PMSEARCHLIST 9-285
#PMSG 9-287
#POP 9-288
#PREFIX 9-289
#PROCESSFILESECURITY 9-292
#PROMPT 9-311
#REPLYPREFIX 9-317
#ROUTEPMSG 9-328
#SHIFTDEFAULT 9-362
#TACLSECURITY 9-399
#TRACE 9-405
#USELIST 9-407
#WAKEUP 9-417
#WIDTH 9-418
Bus 8-32
BUSCMD program 8-32
BYTE data type 4-15
C
Change DEFINE 8-17
Change disk-file name 8-152
Change process priority 8-20
Index
FC 8-63
FILEINFO 8-67
FILENAMES 8-71
FILES 8-73
FILETOVAR 8-74
HELP 8-75
HISTORY 8-76
HOME 8-77
INFO DEFINE 8-78
INITTERM 8-80
INLECHO 8-81
INLEOF 8-82
INLOUT 8-83
INLPREFIX 8-84
INLTO 8-85
JOIN 8-89
KEEP 8-90
KEYS 8-91
LOAD 8-94
LOGOFF 8-97
LOGON 8-99
OBEY 8-109
OUTVAR 8-110
PARAM 8-113
PAUSE 8-116
PMSEARCH 8-118
PMSG 8-120
POP 8-122
PPD 8-126
PURGE 8-128
PUSH 8-130
Question mark (?) 8-264
RECEIVEDUMP 8-138
REMOTEPASSWORD 8-150
RENAME 8-152
RESET DEFINE 8-153
RUN 8-155
SEGINFO 8-167
SET DEFINE 8-172
Index
D
Data type
BOOL 4-15
BYTE 4-15
CHAR 4-15
CRTPID 4-15
DEVICE 4-15
ENUM 4-15
FNAME 4-15
FNAME32 4-16
identifier 4-17
INT 4-16
INT2 4-16
INT4 4-16
PHANDLE 4-16
SSID 4-16
SUBVOL 4-16
TRANSID 4-16
TSTAMP 4-16
UINT 4-16
USERNAME 4-17
VALUE 4-17
Data, allowed characters 2-1
Daylight savings time transition (DST)
table 8-12
DEBUG command 8-48
Debug program 8-48
Debugging breakpoint 8-30
DEFAULT program 8-53
Default settings 8-53
DEFINE
altering 8-17
clearing 8-56
creating 8-9
deleting 8-56
disabling 8-190
displaying content 8-78
enabling 8-190
removing 8-56
restoring attributes 8-153
setting attribute values 8-172
SORT 8-178
SPOOL 8-181
SUBSORT 8-183
TAPE 8-184
Define a variable 4-3
DEFINE templates 2-7
Delete a variable 4-5
Delete ASSIGN 8-33
Delete DEFINE 8-56
DELETE DEFINE command 8-56
Index
E
Editing template 8-64
Enable default debugger 8-192
Enable DEFINE use 8-190
Enable INSPECT 8-192
End-of-line character 2-5
ENUM data type 4-15
ENV command 8-60
Errors 5-21
Exclamation point (!) command 8-263
EXIT command 8-62
Expression evaluation 3-2
F
FALSE result 3-2
FastSort attributes 8-178, 8-183
FC command 8-63
File display 8-71
File listing 8-71
FILEINFO command 8-67
Filename templates 2-7
FILENAMES command 8-71
FILES command 8-73
FILETOVAR command 8-74
FILLER byte 4-20
FNAME data type 4-15
FNAME32 data type 4-16
Function call
DEFINE argument 5-5
device name argument 5-4
filename argument 5-3
Index
H
HELP command 8-75
HIGHPIN range setting 8-191
HISTORY command 8-76
HOME command 8-77
I
Identify a data type 4-17
INFO DEFINE command 8-78
Initialize terminal 8-80
Initiate debugging 8-48
INITTERM command 8-80
INLECHO command 8-81
INLEOF command 8-82
INLOUT command 8-83
INLPREFIX command 8-84
INLTO command 8-85
Inspect program 8-48
INT data type 4-16
INT2 data type 4-16
INT4 data type 4-16
Interactive TACL 1-1
Invoke Debug 8-48
Invoke Inspect 8-48
IPUCOM 8-86
J
JOIN command 8-89
Joining variables 8-89
K
KEEP command 8-90
KEYS command 8-91
L
Levels of variables 4-3
LIGHTS program 8-92
List files 8-71
List logical file names 8-21
List process pairs 8-126
List subvolume files 8-73
List TACL built-in functions 8-31
List TACL built-in variables 8-31
LOAD command 8-94
Load TACL library files 8-94
Load TACL segment file 8-26
LOADEDFILES 8-95
Logical file name assignment 8-21, 8-33
Logical operators 3-1
LOGOFF command 8-97
LOGON command 8-99
M
MACRO 4-7
Macro variable 4-7
Memory dump 8-131, 8-138
Metacharacters 2-2
O
OBEY command 8-109
Operators
arithmetic 3-1
description 2-8
logical 3-1
order of precedence 3-1
Index
relational 3-1
string 3-1
types 3-1
OUTVAR command 8-110
P
PARAM command 8-113
Parameter creation 8-113
PASSWORD program 8-115
PAUSE command 8-116
PHANDLE data type 4-16
PINs and TACL processes 6-2
PMSEARCH command 8-118
PMSG command 8-120
POP command 8-122
Popping variables 4-3
PPD command 8-126
Process completion code 5-16
Process completion-code display 5-20
Process creation and deletion
messages 8-120
Process priority 8-20
Process (suspended) restarting 8-8
Process-pair directory 8-126
Program
file 5-12
extended memory segment 5-13
library 5-13
single variable 5-12
interpretation 5-11
structure 5-9
Programmatic TACL 1-2
Programs
ADDUSER 8-14
ALARMOFF 8-16
BUSCMD 8-32
COPYDUMP 8-42
DEFAULT 8-53
DELUSER 8-57
LIGHTS 8-92
PASSWORD 8-115
RCVDUMP 8-131
RELOAD 8-141
RPASSWRD 8-150
TACL 8-223
USERS 8-231
PURGE command 8-128
PUSH command 8-130
Pushing variables 4-3
Q
Question mark 2-6
Question mark (?) command 8-264
R
RCVDUMP program 8-131
RECEIVEDUMP command 8-138
Relational operators 3-1
Relinquish TACL segment file 8-58
RELOAD program 8-141
Remote password 8-150
REMOTEPASSWORD command 8-150
Remove DEFINE 8-56
RENAME command 8-152
Rename disk file 8-152
Reserved words 2-9
RESET DEFINE command 8-153
Restart suspended process 8-8
Restore DEFINE attribute 8-153
ROUTINE 4-9
Routine variable 4-9
RPASSWRD program 8-150
RUN command 8-155
S
Search subvolume 8-118
Secure a TACL process 6-7
SEGINFO command 8-167
Select swap volume 8-194
SEMSTAT Program 8-168
Index
T
TACL
interactive 1-1
programmatic 1-2
TACL built-in functions 7-2
TACL built-in variables 7-3
TACL commands 7-1
TACL environment
customizing 6-6
TACL environment parameters
display 8-60
TACL file 6-1
Index
U
UINT data type 4-16
Upshifting
characters 2-1
CPRULES0 2-1
CPRULES1 2-1
USE command 8-230
User access
creating 8-14
deleting 8-57
USERNAME data type 4-17
USERS program 8-231
Using TACL
interactively 1-1
programmatically 1-2
V
VALUE data type 4-17
Variable
accessing 4-5
ALIAS 4-6
alias 4-6
allocating 4-3
as an argument 4-6
breakpoint 8-30
changing content 8-197
copy 8-43
creating levels 8-130
declaring 4-3
defining 4-3
deleting 4-5
deleting levels 8-90, 8-122
DELTA 4-30
description 4-7
DIRECTORY 4-28
displaying contents 8-110
joining 8-89
level of 4-3
levels 4-3
Index
MACRO 4-7
names 4-2
naming conflicts 6-10
overview 4-1
popping 4-3
pushing 4-3
ROUTINE 4-9
routine 4-9
specifying a level 4-4
STRUCT 4-12
TEXT 4-6
text 4-6
variable stack 4-3
_EXECUTE 6-11
VARIABLES command 8-233
VARINFO command 8-234
VARTOFILE command 8-236
VCHANGE command 8-237
VCOPY command 8-240
VDELETE command 8-243
VFIND command 8-245
VINSERT command 8-248
VLIST command 8-250
VMOVE command 8-252
VOLUME command 8-255
VTREE command 8-257
W
WAKEUP command 8-258
WHO command 8-259
X
XBUSDOWN command 8-261
XBUSUP command 8-262
Y
YBUSDOWN command 8-261
YBUSUP command 8-262
Special Characters
! command 8-263
#ABEND built-in function 9-12
#ABORTTRANSACTION built-in
function 9-14
#ACTIVATEPROCESS built-in
function 9-15
#ADDDSTTRANSITION built-in
function 9-16
#ALTERPRIORITY built-in function 9-18
#APPEND built-in function 9-19
#APPENDV built-in function 9-20
#ARGUMENT built-in function 9-21
#ASSIGN built-in variable 9-31
#BACKUPCPU built-in function 9-34
#BEGINTRANSACTION built-in
function 9-35
#BREAKMODE built-in variable 9-36
#BREAKPOINT built-in function 9-37
#BUILTINS built-in function 9-38
#CASE built-in function 9-39
#CHANGEUSER built-in function 9-41
#CHARACTERRULES built-in
variable 9-44
#CHARADDR built-in function 9-46
#CHARBREAK built-in function 9-47
#CHARCOUNT built-in function 9-49
#CHARDEL built-in function 9-51
#CHARFIND built-in function 9-53
#CHARFINDR built-in function 9-55
#CHARFINDRV built-in function 9-57
#CHARFINDV built-in function 9-59
#CHARGET built-in function 9-61
#CHARGETV built-in function 9-63
#CHARINS built-in function 9-65
#CHARINSV built-in function 9-67
#COLDLOADTACL built-in function 9-69
#COMPAREV built-in function 9-70
#COMPUTE built-in function 9-71
#COMPUTEJULIANDAYNO built-in
function 9-72
Index
Special Characters
#COMPUTETIMESTAMP built-in
function 9-73
#COMPUTETRANSID built-in function 9-74
#CONTIME built-in function 9-75
#CONVERTPHANDLE built-in
function 9-76
#CONVERTPROCESSTIME built-in
function 9-78
#CONVERTTIMESTAMP built-in
function 9-79
#CREATEFILE built-in function 9-81
#CREATEPROCESSNAME built-in
function 9-83
#CREATEREMOTENAME built-in
function 9-84
#DEBUGPROCESS built-in function 9-85
#DEF built-in function 9-87
#DEFAULTS built-in variable 9-90
#DEFINEADD built-in function 9-92
#DEFINEDELETE built-in function 9-93
#DEFINEDELETEALL built-in function 9-94
#DEFINEINFO built-in function 9-95
#DEFINEMODE built-in variable 9-96
#DEFINENAMES built-in function 9-97
#DEFINENEXTNAME built-in function 9-98
#DEFINEREADATTR built-in function 9-99
#DEFINERESTORE built-in function 9-101
#DEFINERESTOREWORK built-in
function 9-103
#DEFINESAVE built-in function 9-104
#DEFINESAVEWORK built-in
function 9-106
#DEFINESETATTR built-in function 9-107
#DEFINESETLIKE built-in function 9-108
#DEFINEVALIDATEWORK built-in
function 9-109
#DELAY built-in function 9-110
#DELTA built-in function 9-111
#DEVICEINFO built-in function 9-134
#EMPTY built-in function 9-135
#EMPTYV built-in function 9-136
#EMSADDSUBJECT built-in function 9-137
#EMSADDSUBJECTV built-in
function 9-139
#EMSGET built-in function 9-141
#EMSGETV built-in function 9-146
#EMSINIT built-in function 9-150
#EMSINITV built-in function 9-152
#EMSTEXT built-in function 9-154
#EMSTEXTV built-in function 9-156
#ENDTRANSACTION built-in
function 9-158
#EOF built-in function 9-159
#ERRORNUMBERS built-in variable 9-160
#ERRORTEXT built-in function 9-162
#EXCEPTION built-in function 9-163
#EXIT built-in variable 9-164
#EXTRACT built-in function 9-165
#EXTRACTV built-in function 9-166
#FILEGETLOCKINFO built-in
function 9-167
#FILEINFO 9-216
#FILEINFO built-in function 9-170
#FILENAMES built-in function 9-176
#FILTER built-in function 9-178
#FRAME built-in function 9-180
#GETCONFIGURATION built-in
function 9-181
#GETPROCESSSTATE built-in
function 9-184
#GETSCAN built-in function 9-187
#HELPKEY built-in variable 9-188
#HIGHPIN built-in variable 9-189
#HISTORY built-in function 9-190
#HOME built-in variable 9-191
#IF built-in function 9-192
#IN built-in variable 9-194
#INFORMAT 9-274
#INFORMAT built-in variable 9-196
#INITTERM built-in function 9-199
#INLINEECHO built-in variable 9-200
#INLINEEOF built-in function 9-201
#INLINEOUT built-in variable 9-202
#INLINEPREFIX built-in variable 9-203
Index
Special Characters
Index
Special Characters
Index
Special Characters
Index
Special Characters
:UTILS 4-30
:UTILS_GLOBALS 4-30
== 2-10
? 2-6
? command 8-264
?BLANK 5-6
?FORMAT 5-6
?SECTION 5-8
?TACL 5-9
_COMPAREV function 8-37
_CONTIME_TO_TEXT function 8-39
_CONTIME_TO_TEXT_DATE
function 8-40
_CONTIME_TO_TEXT_TIME function 8-41
_DEBUGGER function 8-51
_EXECUTE variable 6-11
_LONGEST function 8-107
_MONTH3 function 8-108
~ 2-5
~_ 2-5
Index
Special Characters