HP TACL Programming Manual

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.

Tandem Computers Incorporated

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).

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.

New and Changed Information

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.

105919 Tandem Computers Incorporated iii

New and Changed Information

(This page left intentionally blank)

iv 105919 Tandem Computers Incorporated

Contents

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

107365 Tandem Computers Incorporated v

Contents

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

vi 107365 Tandem Computers Incorporated

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

Contents

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

107365 Tandem Computers Incorporated vii

Contents

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

viii 107365 Tandem Computers Incorporated

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

Contents

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

107365 Tandem Computers Incorporated ix

Contents

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

x 107365 Tandem Computers Incorporated

About This Manual

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.

107365 Tandem Computers Incorporated xi

About This Manual

Related Reading

(This page left intentionally blank)

xiv 107365 Tandem Computers Incorporated

Notation Conventions

General Syntax

Notation

UPPERCASE LETTERS Uppercase letters indicate keywords and reserved words; enter these items exactly as

lowercase italic letters Lowercase italic letters indicate variable items that you supply. Items not enclosed in

Brackets [ ] Brackets enclose optional syntax items. For example:

The following list summarizes the notation conventions for syntax presentation in this manual.

shown. Items not enclosed in brackets are required. For example:

STATUS

brackets are required. For example:

file-name

TERM [\

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 [

Note also that TACL uses brackets in commands and functions.

node-name

.]$

terminal-name

num

] ]

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.

107365 Tandem Computers Incorporated xv

Notation Conventions

General Syntax Notation

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 [ [,]

xvi 107365 Tandem Computers Incorporated

variable

]...

1 An Overview of TACL

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.

Running the Examples

in This Manual

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.

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

107365 Tandem Computers Incorporated 1–1

An Overview of TACL

Style Conventions

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:

1–2 107365 Tandem Computers Incorporated

[#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

An Overview of TACL

Style Conventions

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

Conventions Specific to

This Manual

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.

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:

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.

107365 Tandem Computers Incorporated 1–3

[#SET temp [#CONTIME [#FILEINFO/MODIFICATION/ [thisfile]]]

#SET temp [#CONTIME [#FILEINFO/MODIFICATION/ & [thisfile]]]

An Overview of TACL

Style Conventions

(This page left intentionally blank)

1–4 107365 Tandem Computers Incorporated

2 Developing TACL Programs

This section describes topics that are common to all types of procedural variables. Topics include:

Defining program structure Processing character data Accessing time information Accessing terminals Debugging TACL programs

The TACL Reference Manual contains information about TACL statements, programs, and the TACL environment. This information is prerequisite to the topics in this and later sections.

Choosing a Type of

Variable

The choice of a type of procedural variable depends on the type of work you plan to do. The variable types can be summarized as follows:

A macro is typically used for programs that have limited need for validation of arguments and no need for conditional exits. Within a macro, you can:

Define and access data structures such as text and STRUCT variables. Compare, move, and manipulate the contents of variables. Process arguments. Use TACL built-in functions and commands, including built-in functions that

provide conditional execution of code. Use TACL built-in variables to specify or obtain information about the TACL

environment.

A routine is the most general and fully functioned type of procedural variable, and is required for programs that handle exceptions (unusual events) or perform complex flow of control operations. If you plan to perform complex argument processing, a routine is recommended.

Routines provide all of the capabilities that are available from macros, plus they support built-in functions such as #ARGUMENT and #RETURN that are not available to macros. While routines can provide more functionality than macros, they also require more knowledge.

This section contains examples that illustrate the use of macros; except where noted, these techniques also apply to routines.

Section 3, “Developing TACL Routines,” discusses additional features that apply only to TACL routines.

107365 Tandem Computers Incorporated 2–1

Developing TACL Programs

Defining Program Structure

Defining Program

Structure

Using Flow Control

Functions

The following paragraphs describe topics that are related to the structure of TACL programs:

Using flow control functions: #LOOP, #IF, and #CASE Nesting programs within other TACL programs Saving and restoring levels of variables Exiting from TACL programs

The following examples show how #LOOP, #CASE, and #IF statements work. The macro in Figure 2-1, copier, demonstrates two ways to perform an activity in a

loop. Copier makes six copies of a file named TYPE. (The file TYPE must exist before you run copier.) For the first three duplications, copier starts a new FUP process during each pass through a loop. For the second three duplications, copier loops to prepare a sequence of commands and then passes the commands to FUP. The second method requires one additional variable and one more function call but starts only one FUP process, and is therefore more efficient.

When you run copier, your TACL process must be named (using the NAME option with the TACL command). To run copier, load the file that contains the macro and then type:

copier

Figure 2-1. Performing Tasks Within a Loop

?SECTION copier MACRO #FRAME #PUSH listvar == List of files to be duplicated #PUSH sn == Serial number

== Less efficient method; multiple processes started #SET sn 0 [#LOOP |DO| FUP DUP type, tmpa[sn] == Start FUP for each #SET sn [#COMPUTE sn + 1] == command in the loop |UNTIL| (sn = 3) ] == More efficient method; one process started #SET sn 0 [#LOOP |DO| #APPEND listvar DUP type, tmpb[sn] #SET sn [#COMPUTE sn + 1] |UNTIL| (sn = 3) ] FUP/INV listvar/ == Execute FUP only once #UNFRAME

2–2 107365 Tandem Computers Incorporated

Developing TACL Programs

Defining Program Structure

You can define a macro that increments a loop variable (passed as the argument); for example:

[#DEF next MACRO |BODY| #SET %1% [#COMPUTE %1% + 1] ]

Use the macro in Figure 2-2, bubble, with its nested #LOOP statements, to perform a bubble sort. A bubble sort compares numbers and switches their places until the numbers are stored in ascending order.

To run bubble, load its file and supply the number of sort elements as an argument:

bubble

num

Figure 2-2. Performing a Bubble Sort With Nested #LOOP Statements (Page 1 of 2)

?SECTION bubble MACRO #FRAME

#PUSH i j max ocount element prompt temp #SETMANY i j max ocount element, 0 0 0 0 0 #SET prompt Enter Next Number to be Sorted...

== Request the number of elements specified in argument 1 and == store them in levels of STACK [#LOOP |WHILE| (element < %1%) |DO| #PUSH stack #INPUTV stack prompt #SET element [#COMPUTE element + 1] ] {end of INPUT loop}

== Loop once for each element #SET ocount 1 [#LOOP |WHILE| (ocount < %1%) |DO| #SET i 1 #SET max [#COMPUTE %1% - ocount + 1]

== Compare each element to its adjacent number; switch places == if we encounter a smaller number. [#LOOP |WHILE| (i < max) |DO| #SET j [#COMPUTE i + 1] [#IF ([stack.i] > [stack.j]) |THEN| #SET temp [stack.i] #SET stack.i stack.j #SET stack.j temp ] #SET i [#COMPUTE i + 1] ] {end of inner loop} #SET ocount [#COMPUTE ocount + 1] ] == end of outer loop

107365 Tandem Computers Incorporated 2–3

Developing TACL Programs

Defining Program Structure

Figure 2-2. Performing a Bubble Sort With Nested #LOOP Statements (Page 2 of 2)

== Loop through all variable levels and display contents #SET element 1 [#LOOP |DO| #OUTPUT [stack.[element]] #SET element [#COMPUTE element + 1] |UNTIL| (element > %1%) ] #UNFRAME

Bubble requests the specified number of elements and displays the results:

29> bubble 3 Enter Next Number to be Sorted...1 Enter Next Number to be Sorted...43 Enter Next Number to be Sorted...5 1 5 43 30>

The bubble macro does not check the data type of the argument. Therefore, bubble abc causes an error:

29> bubble abc

[#IF ( ( 0 < abc) )

Expecting a constant Or NOT Or a string (variable does not exist) Or a number Or (

30>

Use the routine in Figure 2-3, checkfiles, with its #IF statements and nested #CASE statements, to perform file maintenance on a subvolume. The routine asks for an alphanumeric starting point in the subvolume. It starts at the next file name, loops through your current subvolume, and displays information about each file in the subvolume.

Note When you run checkfiles, you must access your local system and your node name must not be

included in your current #DEFAULTS. To remove a node name, if present, enter SYSTEM at the TACL prompt before running checkfiles.

2–4 107365 Tandem Computers Incorporated

Developing TACL Programs

Defining Program Structure

When you run checkfiles, the routine displays the following:

Where do you want to start (default = beginning of subvol)?

To start checking files in the middle of the subvolume, enter a text constant with the desired starting characters. Checkfiles then performs the following steps for each file past the specified starting point in the subvolume:

1. Checkfiles displays the file name and date of last alteration.

2. For an Edit file, checkfiles displays the first ten lines of the file; otherwise, it

displays “Not an Edit file; nothing to show you.”

3. Checkfiles asks if you want to purge the file (Y or N). For files that are not Edit

files, checkfiles also asks if you want to empty the file (E).

Checkfiles stops at the end of the subvolume; to stop earlier, press BREAK.

Figure 2-3. Deleting Files in a Subvolume (Page 1 of 2)

?SECTION checkfiles ROUTINE #FRAME #PUSH filenm reply prompt volsubvol thisone temp resp #SET thisone [#DEFAULTS/CURRENT/] #SET volsubvol [thisone]

#SET prompt & Enter the start file (default = beginning of subvol)?

== Read text from the terminal #INPUTV filenm prompt #SET filenm [#NEXTFILENAME [#SHIFTSTRING/UP/[filenm]] ] [#SET volsubvol [#FILEINFO/VOLUME/[filenm]].[#FILEINFO/SUBVOL/[filenm]] ]

== Loop within the same subvolume [#LOOP |WHILE| ([_COMPAREV volsubvol thisone]) |DO| == Display last-altered information #SET temp [#CONTIME [#FILEINFO/MODIFICATION/ [filenm]]] #OUTPUT #OUTPUT [filenm] last altered [_CONTIME_TO_TEXT [temp]] == Get the file code [#CASE [#FILEINFO/CODE/ [filenm] ] == If an edit file, list the first ten lines, then == determine whether the user wants to purge the file |101| FUP COPY [filenm] , , COUNT 10 #SET prompt Do you want to purge [filenm] (y/n)? #INPUTV reply prompt

107365 Tandem Computers Incorporated 2–5

Developing TACL Programs

Defining Program Structure

Figure 2-3. Deleting Files in a Subvolume (Page 2 of 2)

[#IF [#MATCH Y* [#SHIFTSTRING/UP/[reply]]] |THEN| #SET resp [#PURGE [filenm]] [#CASE [resp] |0| #OUTPUT [filenm] purged |OTHERWISE| #OUTPUT [filenm] could not be purged #OUTPUT Error [resp] ] {end #CASE} ] {end #IF}

|OTHERWISE| == Not an edit file; determine whether to purge it #OUTPUT Not an Edit file; nothing to show you. #SET prompt Do you want to purge/empty [filenm] & (y/n/e)? #INPUTV reply prompt

[#IF [#MATCH E* [reply]] |THEN| == empty the file FUP PURGEDATA [filenm] ] ] == end #CASE

== Get the next file #SET filenm [#NEXTFILENAME [filenm] ] [#SET volsubvol [#FILEINFO/VOLUME/[filenm]].[#FILEINFO/SUBVOL/[filenm]] ] == end #SET ] == end #LOOP #UNFRAME

Note The previous example starts FUP several times; a more efficient way is to start FUP once and send it a

series of commands. For information about starting a process and sending it commands, see Section 5, “Initiating and Communicating with Processes.”

2–6 107365 Tandem Computers Incorporated

Developing TACL Programs

Defining Program Structure

Nesting TACL Code To run another TACL program from within a TACL program, invoke the file name or

variable name, as appropriate. Certain built-in functions can be used only within one type of program (macro or

routine). To determine the use of such functions in a nested program, see individual function descriptions in the TACL Reference Manual. For example, #ARGUMENT must be used within a routine, but can be used in a macro if the macro is nested within a routine.

To call a program recursively, use %0% (for a macro) or #ROUTINENAME (for a routine) to specify the name of the program. You cannot call a text variable recursively.

The following macro calls itself to display each of its arguments on a separate line:

?TACL MACRO #OUTPUT %1% == Display current argument [#IF NOT [#EMPTY %2%] |THEN| == Test for additional arguments %0% %2 TO *% == Call self without current ] == argument.

To run this macro, type the file name from the TACL prompt and supply one or more arguments. The macro displays the arguments you supply. In the following example, the file name that contains the macro is called ARGS:

12> args a b c d a b c d 13>

Section 3, “Developing TACL Routines,” contains a macro that calls a nested routine.

107365 Tandem Computers Incorporated 2–7

Developing TACL Programs

Defining Program Structure

Use the macro in Figure 2-4, defaultvars, to assign data to a set of empty variables. The macro accepts a space-separated list of variables and nonempty values and calls itself repeatedly until all arguments are processed. To run this macro, load the file that contains the macro definition and then type:

12> defaultvars [

variable constant [variable constant

Figure 2-4. Processing Macro Arguments

?SECTION defaultvars MACRO

== Any more pairs? [#IF NOT [#EMPTY %1%] |THEN|

== Is this variable empty? [#IF [#EMPTYV %1%] |THEN|

== The variable is empty; install default value #SET %1% %2% ]

== Call self again, omitting the current pair. %0% %3 TO *% ]

The following session shows how defaultvars works:

15> #PUSH a b c 16> defaultvars a 3 b 4 c 5

...] ]

17> #OUTPUTV a 3 18> #OUTPUTV b 4 19> #OUTPUTV c 5

Saving Levels of Variables The #PUSH built-in function creates a new level for a user-defined or built-in variable.

If you push a variable twice, TACL creates two levels of the variable. A new level remains in existence until you request a #POP, #UNFRAME, or #RESET FRAMES operation.

The following code redefines the TACL OUT file, retrieves information from the history buffer, saves the history information in a file named HISTFILE in the current subvolume, and then restores the OUT file to its previous setting:

?SECTION historysave MACRO #PUSH #OUT == Create a new level for #OUT #SET #OUT histfile == Set OUT to HISTFILE #HISTORY == Retrieve history information #POP #OUT == Restore #OUT to its previous value

2–8 107365 Tandem Computers Incorporated

Developing TACL Programs

Processing Character Data

The #FRAME built-in function creates a local environment for variables. The #UNFRAME command restores variables to the state they were in at the time of the last #FRAME operation. For more information about frames, see the TACL Reference

Manual.

Exiting From Programs TACL exits from a macro or text variable as soon as it encounters either of the

following conditions:

Successful completion of the code; TACL executes each line and exits when finished.

Detection of an error condition, in which case TACL restores all variables to the state they were in when the variable was invoked and then exits the variable.

If you use routine variables, you can use the #RETURN built-in function to return conditionally from one or more locations in your code. For more information, see “Returning Results” in Section 3, “Developing TACL Routines.”

Processing Character

Data

When writing a TACL program, you might need to examine or modify the contents of variables. Such tasks include:

Constructing text strings for input to processes, files, or devices Analyzing process output Analyzing results of functions

For example, whenever you use RUN or #NEWPROCESS to initiate a process from TACL, you can direct output from the process to a variable:

The OUT option directs program output to a file. The OUTV option stores program output into a variable for later use.

Section 5, “Initiating and Communicating With Processes,” describes process initiation.

TACL supports several commands and functions that manipulate characters and lines of characters within variables:

Commands, typically used for interactive work, perform editing operations on one or more lines in a variable.

Built-in functions perform a single operation, referencing text by character position or line number.

#DELTA, the low-level character editor, provides text editing capabilities similar to those provided by the character and line oriented built-in functions. #DELTA is complex; the newer #CHARxxx and #LINExxx built-in functions are easier to use.

STRUCT variables, or structures, allow you to define a set of elements and access the elements by name. STRUCT variables support a range of data types. Structures are helpful when communicating with processes such as $CMON, and are required when communicating with the Subsystem Programmatic Interface (SPI) and the Event Management Service (EMS).

107365 Tandem Computers Incorporated 2–9

Developing TACL Programs

Processing Character Data

Note Variable levels that contain TACL code contain special internal multicharacter representations of [, |,

For additional information about #DELTA and STRUCT variables, see the TACL Reference Manual. For examples showing the use of STRUCT variables with SPI and

EMS, see Section 7, “Using Programmatic Interfaces.” The following paragraphs describe how to use string manipulation functions and

commands.

and ]. When you use character oriented functions, be aware that these representations are counted as multiple characters; they contain unprintable characters that are subject to change from one release of TACL to another.

Line and Character

Built-In Functions

The functions in Table 2-1 operate on the contents of variables; each of these functions performs an action and/or returns a result. There are two types of functions—one accepts a character address; the other accepts a line address. Table 2-1 lists both types of built-in functions; a dash indicates that there is no equivalent function or command.

Table 2-1. Built-In Functions That Edit Variables by Line

Character Address Function

Line Address Function Description

#CHARADDR #LINEADDR Converts between a character address and a line

address.

#CHARBREAK #LINEBREAK Inserts a line break at the specified character or

line address. #CHARCOUNT #LINECOUNT Counts characters or lines. #CHARDEL #LINEDEL Deletes consecutive characters or lines. #CHARFIND #LINEFIND Finds the address of specified text, searching

forward. #CHARFINDV #LINEFINDV Finds the address of a specified string, searching

forward. #CHARFINDR #LINEFINDR Finds the address of specified text, searching

backward. #CHARFINDRV #LINEFINDRV Finds the address a specified string, searching

backward. #CHARGET #LINEGET Returns a copy of consecutive characters or lines. #CHARGETV #LINEGETV Places a copy of consecutive characters or lines

in the variable. #CHARINS #LINEINS Inserts lines of text at a specified address in the

variable. #CHARINSV #LINEINSV Inserts a string at a specified address in the

variable. — #LINEJOIN Joins two lines.

2–10 107365 Tandem Computers Incorporated

+ 205 hidden pages

HP TACL Programming Manual

Specifications and Main Features

Frequently Asked Questions

User Manual