HP TACL Operating instructions

Tandem Computers Incorporated
System Software Library
TACL
Programming
Guide
Abstract This manual describes the Tandem Advanced Command Language (TACL) and provides information and
examples for creating TACL programs.
Part Number 107365
Edition Second
Published December 1994
Product Version TACL D30
Release ID D30.00
Supported Releases This manual supports D30.00 and all subsequent releases until otherwise indicated in a new edition.

Ordering Information For manual ordering information: domestic U.S. customers, call 1-800-243-6886; international customers, contact your
local sales representative.
Document Disclaimer Information contained in a manual is subject to change without notice. Please check with your authorized Tandem
representative to make sure you have the most recent information.
Export Statement Export of the information contained in this manual may require authorization from the U.S. Department of Commerce.
Examples Examples and sample programs are for illustration only and may not be suited for your particular purpose. Tandem does
not warrant, guarantee, or make any representations regarding the use or the results of the use of any examples or sample
programs in any documentation. You should verify the applicability of any example or sample program before placing the
software into productive use.
U.S. Government
Customers FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED SOFTWARE:
These notices shall be marked on any reproduction of this data, in whole or in part.
NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this computer
software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in Section 52.227-19
of the FARS Computer Software-Restricted Rights clause.
RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the restrictions as set
forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013.
RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth
in paragraph (b)(3)(B) of the rights in Technical Data and Computer Software clause in DAR 7-104.9(a). This computer
software is submitted with “restricted rights.” Use, duplication or disclosure is subject to the restrictions as set forth in
NASA FAR SUP 18-52 227-79 (April 1985) “Commercial Computer Software — Restricted Rights (April 1985).” If the
contract contains the Clause at 18-52 227-74 “Rights in Data General” then the “Alternate III” clause applies.
U.S. Government Users Restricted Rights — Use, duplication or disclosure restricted by GSA ADP Schedule Contract.
Unpublished — All rights reserved under the Copyright Laws of the United States.
Document History Edition Part Number Product Version Earliest Supported Release Published
First 085797 TACL C20 N/A November 1992
Update 086700 TACL D10 N/A February 1993
Second 107365 TACL D30 D30.00 December 1994
New editions incorporate any updates issued since the previous edition.
A plus sign (+) after a release ID indicates that this manual describes function added to the base release,
either by an interim product modification (IPM) or by a new product version on a .99 site update tape (SUT).

New and Changed Information
105919 Tandem Computers Incorporated iii
This is the second edition of the TACL Programming Guide . This edition documents
the following new TACL features:
A new built-in function, #SETCONFIGURATION, sets the TACL flags that can
change the behavior of TACL for a specified TACL image or configure the
currently running TACL process.
A new built-in function, #XLOGON, implements the LOGON command.
The LOGON command, #CHANGEUSER built-in function, and #XLOGON built-
in function support the Safeguard authentication dialog.
The STATUS command and #XSTATUS built-in function display new process
type information.
CLASS DEFAULT DEFINEs have eight new optional attributes for
internationalization support.

New and Changed Information
iv 105919 Tandem Computers Incorporated
(This page left intentionally blank)

Contents
107365 Tandem Computers Incorporated v
About This Manual xi
Notation Conventions xv
Section 1 An Overview of TACL
Running the Examples in This Manual 1-1
Style Conventions 1-2
Exceptions to the Style Conventions 1-3
Conventions Specific to This Manual 1-3
Section 2 Developing TACL Programs
Choosing a Type of Variable 2-1
Defining Program Structure 2-2
Using Flow Control Functions 2-2
Nesting TACL Code 2-7
Saving Levels of Variables 2-8
Exiting From Programs 2-9
Processing Character Data 2-9
Line and Character 2-10
Global Editing Commands 2-13
Additional Data Manipulation Capabilities 2-16
Data Types 2-17
Accessing Time Data 2-17
Timestamp Formats 2-17
Retrieving a Timestamp 2-18
Converting a Timestamp 2-19
Accessing Terminals 2-24
Defining Function Keys 2-24
Sending Escape Sequences to a Terminal 2-25
Changing the TACL Prompt 2-29
Implementing Menus 2-30
Debugging TACL Programs 2-32
Enabling the TACL Debugger 2-32
Debugger Commands 2-32
A Sample Debugging Session 2-33

Contents
vi 107365 Tandem Computers Incorporated
Section 3 Developing TACL Routines
Processing Arguments 3-1
How #ARGUMENT Works 3-3
Using #ARGUMENT 3-4
Examining the Contents of Arguments 3-9
Parsing Arguments for a Caller 3-11
Returning Results 3-15
Calling a Routine Recursively 3-16
Exiting From a Routine 3-17
Writing an Exception Handler 3-18
Types of Exception Handlers 3-19
Constructing an Exception Handler 3-19
Creating a Release Exception Handler 3-20
Creating a Keep Exception Handler 3-24
Combining Keep and Release Handlers 3-30
Section 4 Accessing Files
#REQUESTER Operation 4-1
Requesting Waited Reads 4-2
Requesting Nowaited Reads 4-4
Requesting Waited Writes 4-6
Requesting Nowaited Writes 4-8
Copying Records Between Files 4-10
Comparing Files 4-12
Listing a File 4-16
Section 5 Initiating and Communicating With Processes
Initiating a Process 5-2
Using RUN and #NEWPROCESS Options 5-2
Sending Information at Initiation Time 5-3
Communicating With a Process 5-4
Using the INLINE Facility 5-6
Using INV and OUTV 5-14
Using $RECEIVE 5-21
Using #SERVER 5-29
Using Define Process 5-31

Contents
107365 Tandem Computers Incorporated vii
Processing Completion Information 5-32
Processing NetBatch Jobs and Completion Codes 5-32
Monitoring Job Status
ENQUIRY 5-35
Section 6 Running TACL as a Server
Running a TACL Process as a Server 6-1
Starting TACL as a Server Process 6-1
Sending Requests to a TACL Server 6-2
Directing Output From TACL 6-4
Running TACL Code as a Server 6-5
Constructing a TACL Server 6-5
Using TACL as a Pathway Server 6-6
Section 7 Using Programmatic Interfaces
Overview of SPI and EMS 7-1
Using SPI 7-4
Defining an SPI Buffer 7-5
Using SPI Functions 7-9
Using EMS 7-12
Communicating With EMS 7-12
Generating an EMS Event 7-13
Section 8 Example of a System Management Program
Monitoring System Operation 8-1
Section 9 Syntax Summary
TACL Commands and Functions 9-1
Built-In Functions and Variables 9-6
STRUCT Declarations 9-14
#SET Summary 9-15
#DELTA Command Summary 9-16
Appendix A Supplemental Information for D-Series Systems
Glossary Glossary–1

Contents
viii 107365 Tandem Computers Incorporated
Index Index–1
Figures Figure 2-1. Performing Tasks Within a Loop 2-2
Figure 2-2. Performing a Bubble Sort With Nested #LOOP Statements 2-3
Figure 2-3. Deleting Files in a Subvolume 2-5
Figure 2-4. Processing Macro Arguments 2-8
Figure 2-5. Extracting a Volume Name from a Variable 2-12
Figure 2-6. Retrieving Disk Names From DSAP 2-15
Figure 2-7. Relationships Between System Timestamps and TACL
Functions 2-20
Figure 2-8. Relationships Between #FILEINFO Timestamps and TACL
Functions 2-21
Figure 2-9. Computing the Current Day 2-22
Figure 2-10. Converting Timestamps 2-23
Figure 2-11. Sending Special Characters to a Screen 2-25
Figure 2-12. Displaying a Screen of Text 2-27
Figure 2-13. Locking a Terminal 2-28
Figure 2-14. Displaying a Menu 2-30
Figure 2-15. Starting TEDIT From TACL 2-34
Figure 3-1. Processing Arguments 3-5
Figure 3-2. Returning Characters From a Routine 3-9
Figure 3-3. Returning a Set of Characters From a Variable 3-10
Figure 3-4. Searching for Text 3-10
Figure 3-5. Counting Characters in a Variable 3-11
Figure 3-6. Moving Text Between Variables 3-11
Figure 3-7. Assigning Values to Arguments 3-12
Figure 3-8. Sending Arguments to a Parsing Program 3-14
Figure 3-9. Converting Timestamps 3-15
Figure 3-10. Processing Arguments 3-16
Figure 3-11. Processing File Name Arguments 3-17
Figure 3-12. Sample Release Handler Template 3-20
Figure 3-13. Sample Release Handler 3-21
Figure 3-14. Returning Information From a Release Handler 3-22
Figure 3-15. Sample Keep Exception Handler 3-25

Contents
107365 Tandem Computers Incorporated ix
Figure 3-16. Sample Command Shell 3-27
Figure 3-17. Using Nested Keep and Release Handlers (Page 1 of 2) 3-31
Figure 4-1 Performing a Waited Read 4-3
Figure 4-2 Performing a Nowaited Read 4-5
Figure 4-3 Reading From a Terminal and Performing a Waited Write 4-7
Figure 4-4 Reading From a Terminal and Performing a Nowaited
Write 4-9
Figure 4-5 Copying Records From One File to Another File 4-10
Figure 4-6 Comparing Two Files 4-13
Figure 4-7 Listing a File 4-16
Figure 4-8 TACLLIST Output 4-20
Figure 5-1 Communicating With FUP 5-8
Figure 5-2 Building a Script 5-8
Figure 5-3 Retrieving Output from FUP 5-10
Figure 5-4 Omitting Terminal Output 5-11
Figure 5-5 Deleting PERUSE Jobs 5-12
Figure 5-6 Retrieving the TACL IN File Name 5-15
Figure 5-7 Communicating With FUP Using INV and OUTV 5-17
Figure 5-8 Directing FUP Output to a Log File 5-18
Figure 5-9 Displaying PERUSE Jobs 5-19
Figure 5-10 Sending Messages to a Terminal 5-22
Figure 5-11 Creating CMON Messages 5-25
Figure 5-12 Communicating With FUP Using #SERVER 5-30
Figure 5-13 Checking Completion Codes 5-33
Figure 5-14 Retrieving TACL Output 5-36
Figure 6-1 Starting and Sending Requests to a TACL Server 6-2
Figure 6-2 Running a TACL Program as a Server 6-7
Figure 6-3 Screen COBOL Code That Accesses a TACL Server 6-9
Figure 6-4 Configuring the Pathway Environment 6-11
Figure 7-1 Comparing Two Subsystem IDs 7-9
Figure 7-2 Displaying the EMS Log 7-10
Figure 7-3 Generating an EMS Event 7-13
Figure 8-1 Monitoring System Status 8-2

Contents
x107365 Tandem Computers Incorporated
Tables Table 2-1. Built-In Functions That Edit Variables by Line 2-10
Table 2-2. Global Editing Commands 2-13
Table 2-3. Data Manipulation Functions 2-16
Table 2-4. Timestamp Conversion Functions 2-19
Table 2-5. _DEBUGGER Command Syntax 2-32
Table 3-1. Functions That Support Arguments 3-3
Table 3-2. Functions That Support Exception Handlers 3-19
Table 3-3. Differences Between Keep and Release Exception
Handlers 3-20
Table 4-1 Functions Used With #REQUESTER 4-2
Table 5-1 RUN and #NEWPROCESS Communication Options 5-2
Table 5-2 INLINE Commands and Variables 5-6
Table 5-3 Variables and Commands for INLINE Display 5-9
Table 5-4 Functions and Options Used With INV and OUTV 5-15
Table 5-5 Functions to Use With $RECEIVE 5-21
Table 6-1 Functions That Support Interprocess Communication 6-2
Table 7-1 TACL Functions That Support SPI 7-4
Table 7-2 SPI Token Data Types 7-6
Table 7-3 Functions That Support EMS 7-12

About This Manual
107365 Tandem Computers Incorporated xi
This manual describes the Tandem Advanced Command Language (TACL) and
provides information and examples for creating TACL programs.
Audience This manual is intended for users of TACL who are familiar with TACL commands
and built-in functions and who want to create TACL programs.
Organization This manual contains the following sections:
Section 1, “An Overview of TACL,” contains an overview of TACL features and a
description of the programming conventions used in examples.
Section 2, “Developing TACL Programs,” describes topics that are common to
many TACL programs, whether they are structured as TEXT, MACRO, or
ROUTINE variables. Topics include data editing, flow of control, using time data,
accessing terminals, handling errors, and debugging TACL programs.
Section 3, “Developing TACL Routines,” describes how to use TACL constructs
that are available only for routines, including the use of #ARGUMENT,
#RETURN, and #ROUTINENAME.
Section 4, “Accessing Files,” provides information and examples that show how
to access files from TACL programs.
Section 5, “Initiating and Communicating With Processes,” provides information
and examples that show how to start and communicate with processes from TACL
programs.
Section 6, “Running TACL as a Server,” describes how to create a TACL program
that acts as a server to other processes.
Section 7, “Using Programmatic Interfaces,” provides information and examples
for sending SPI and EMS messages.
Section 8, “Example of a System Management Program,” contains a sample
program that monitors system status.
Section 9, “Syntax Summary,” provides a syntax summary of all TACL functions.
Appendix A, “Supplemental Information for D-Series Systems,” provides
information on D-series features.
Related Reading The following paragraphs list manuals that are related to the development of TACL
programs.
Prerequisites Introductory material describing the steps involved in using TACL as a command
interpreter, as well as using it for defining function keys, writing simple macros, and
other basic purposes, is presented in the Guardian User’s Guide (contains no
descriptions of TACL built-in functions and variables). You should read and
understand the first four sections of that manual before using this programming
guide.

Related Reading
About This Manual
xii 107365 Tandem Computers Incorporated
To use this manual, you should be familiar with the syntax and structure of procedural
variables (TEXT, MACRO, and ROUTINE), including basic programming concepts
and terminology such as “pushing” and “popping” (creating and deleting) variables,
the use of arguments, and so on. Elements of the TACL language are described in the
TACL Reference Manual.
Corequisites Additional sources of information you might want to have available for reference are:
Debug Manual
Event Management Service (EMS) Manual
Enscribe Programmer’s Guide
Expand Network Management Guide
File Utility Program (FUP) Reference Manual
Guardian Programmer’s Guide
Introduction to Distributed Systems Management (DSM)
Distributed Systems Management (DSM) Programming Manual
Inspect Manual
NetBatch Manual
Security Management Guide
System Procedure Errors and Messages Manual
NonStop II and TXP System Operator’s Guide
System Procedure Calls Reference Manual, Volume 1 and 2
Introduction to NonStop Transaction Manager/MP (TM/MP)
ViewPoint Manual

Related Reading
About This Manual
107365 Tandem Computers Incorporated xiii
Figure 1 lists the recommended sequence for reading TACL related manuals.
Figure 1. Documentation Road Map
001
Guardian
User's Guide
TACL
Programming
Guide
TACL
Reference
Manual
NetBatch
Manual Guardian
Programmer's
Guide
Event
Management
Service (EMS)
Manual
Introduction to
Distributed
Systems
Management
(DSM)
Related Manuals
Prerequisite Manuals

Related Reading
About This Manual
xiv 107365 Tandem Computers Incorporated
(This page left intentionally blank)

Notation Conventions
107365 Tandem Computers Incorporated xv
General Syntax
Notation The following list summarizes the notation conventions for syntax presentation in this
manual.
UPPERCASE LETTERS Uppercase letters indicate keywords and reserved words; enter these items exactly as
shown. Items not enclosed in brackets are required. For example:
STATUS
lowercase italic letters Lowercase italic letters indicate variable items that you supply. Items not enclosed in
brackets are required. For example:
file-name
Brackets [ ] Brackets enclose optional syntax items. For example:
TERM [\ node-name .]$ terminal-name
A group of items enclosed in brackets is a list from which you can choose one item or
none. The items in the list may 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:
LIGHTS [ ON ]
[ OFF ]
[ SMOOTH [ num ] ]
Note also that TACL uses brackets in commands and functions.
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 may 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:
#BUILTINS [ / { FUNCTIONS | VARIABLES } / ]
Note also that TACL uses braces in comments.
Vertical Line | A vertical line separates alternatives in a horizontal list that is enclosed in brackets or
braces. For example:
INSPECT { OFF | ON | SAVEABEND }
Note also that TACL uses vertical lines to surround labels in enclosures.

General Syntax Notation
Notation Conventions
xvi 107365 Tandem Computers Incorporated
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:
#PUSH variable [ [,] variable ] ...
[ + | - ] {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.
Punctuation Parentheses, commas, semicolons, and other symbols not previously described must
be entered as shown. For example:
#CHARACTERRULES
Quotation marks around a symbol such as a bracket or brace indicate the symbol is a
required character that you must enter as shown.
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:
PURGE file-name
If there is no space between two items, spaces are not permitted. In the following
example, there are no spaces permitted between the period and any other items:
$ subvol . file-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 a blank line. This
spacing distinguishes items in a continuation line from items in a vertical list of
selections. For example:
#POP variable
[ [,] variable ]...

1 An Overview of TACL
107365 Tandem Computers Incorporated 1–1
The Tandem Advanced Command Language (TACL) is the standard command
interface to the Tandem NonStop kernel. In addition to providing full command
interpreter facilities, TACL is a high-level programming language.
As a programming language, the TACL product is most often used for managing
systems and processes. You can, for example, use TACL to:
Automate system startup and shutdown procedures.
Automate subsystem startup and shutdown procedures; for example, you can use
TACL statements to initialize Pathway, the TMF subsystem, Transfer, and other
subsystems.
Run utilities and issue commands−either with a fixed set of commands or a
flexible set that you can tailor at run time.
Create a customized environment that simplifies commonly performed tasks for
users.
Control subsystem operation using the Subsystem Programmatic Interface (SPI).
Communicate with the Event Management Service (EMS) and generate EMS
messages.
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; all of the commands supplied by Tandem are implemented as
TACL programs. You can add functions as necessary.
In addition, NetBatch requires the use of TACL.
The following paragraphs describe programming style and the use of examples in this
manual.
Running the Examples
in This Manual Before running the examples in this manual, set the built-in variable #INFORMAT to
TACL, which enables recognition and processing of the TACL special characters ([ and
], for example); without this step, TACL does not recognize metacharacters as special
characters. The function call is:
11> #SET #INFORMAT TACL
In addition, set the built-in variable #PMSEARCHLIST to include (at least)
$SYSTEM.SYSTEM and the keyword #DEFAULTS, which enable the use of implied
RUN commands. An example is:
12> #SET #PMSEARCHLIST [#DEFAULTS] $SYSTEM.SYSTEM

Style Conventions
An Overview of TACL
1–2 107365 Tandem Computers Incorporated
You can add these statements to your TACLCSTM file if you use them frequently.
In cases where TACL provides a built-in function that is similar to a command (such
as PUSH and #PUSH), the examples in this manual use the built-in function. Built-in
functions are the most basic unit of TACL, and they return results and provide easier
programmatic access to error information.
Error checking is as important in TACL programs as it is in programs written in other
languages. Possible sources for errors include terminal input and file system
operations.
Examples and sample programs are for illustration only and might not be suited for
your particular purpose. Tandem does not warrant, guarantee, or make any
representations regarding the use or the results of the use of any examples or sample
programs in any documentation. You should verify the applicability of any example
or sample program before placing the software into productive use.
Note For additional examples, you can view the code for TACL commands by displaying the contents
(#OUTVAR command ).
Style Conventions The examples in this manual adhere to the following conventions for clarity and
maintainability of programs:
Built-in functions, commands, variables, and other keywords appear in uppercase:
#SET
TIME
User-defined functions, commands, and variables appear in lowercase:
var1
get_info
STRUCT definitions are indented two columns for each level of nesting.
Similar levels of nested text in #IF, #CASE, and #LOOP statements are indented to
the same column. Indentations are in two-space increments. Matching square
brackets are in the same column; labels within square brackets start at the same
column.
Square brackets and labels for #IF and #LOOP statements start at the same
column. Conditional text is indented two more spaces. For example:
[#IF [timenow] > 12 |THEN|
#OUTPUT Good afternoon
|ELSE|
#OUTPUT Good morning
]
Square brackets for #CASE statements start at the same column. Because
#CASE statements can include include several user defined labels; labels are

Style Conventions
An Overview of TACL
107365 Tandem Computers Incorporated 1–3
indented two spaces within the square brackets. Conditional text is indented
two spaces past the labels. For example:
[#CASE [errornumber]
|0|
#OUTPUT [filename] was purged
|OTHERWISE|
#OUTPUT [filename] could not be purged
#OUTPUT Error [errornumber]
]
Exceptions to the Style
Conventions In a few situations, the preceding style conventions do not produce optimal results. For example, an #OUTPUT call that continues on a second line includes leading spaces
in the display. Therefore, text that continues an #OUTPUT call should be left-justified.
For example:
[#IF [x] > 0 |THEN|
#OUTPUT This is a test; the text for this #OUTPUT call &
is longer than a single line.
]
The second line of the #OUTPUT call is not indented two spaces.
In such cases, the examples in this manual note the exception and do not follow the
style conventions.
Conventions Specific to
This Manual The following additional conventions are used for consistency:
The COMPUTE command and the #COMPUTE, #IF, and #LOOP built-in
functions accept expressions as arguments. When you supply a variable name as
all or part of an expression, you can enclose the variable name in square brackets
or omit the square brackets. Either way, TACL retrieves the contents of the
variable.
The examples in this manual include the square brackets, to show that the
statement uses the contents of the variable. This approach, however, requires
slightly more processing by TACL.
The examples in this manual are restricted to a line length of 62 characters (as
opposed to 80 characters for an edit file). There are several function calls in this
manual that are longer than 62 characters; these calls are enclosed in square
brackets or are joined by an ampersand character:
[#SET temp [#CONTIME [#FILEINFO/MODIFICATION/
[thisfile]]]
#SET temp [#CONTIME [#FILEINFO/MODIFICATION/ &
[thisfile]]]
Lines that have 80 characters or less can fit on one edit file line; if you join these
lines in your program, you can omit the surrounding square brackets or the
ampersand character.
For more information about expressions, see the TACL Reference Manual.

Style Conventions
An Overview of TACL
1–4 107365 Tandem Computers Incorporated
(This page left intentionally blank)