System Software Library NonStop NET/MASTER NCL Programmer’s Guide Abstract Part Number Edition Published Product Version Release ID Supported Releases This manual describes how to use the NonStop NET/MASTER Network Control Language (NCL). This manual is intended for all NonStop NET/MASTER users who write and maintain NCL procedures. 106160 First December 1994 NonStop NET/MASTER D30 D30.00 This manual supports D30.00 and all subsequent releases until otherwise indicated in a new edition.
Document History Edition Part Number Product Version First Second First 057255 094891 106160 T6581C30 T6581C31 Earliest Supported Release C30.08 C30.09+ NonStop NET/MASTER D30 D30.00 Published August 1992 June 1993 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 .
New and Changed Information The operating system for Tandem NonStop systems, formerly called the Guardian operating system, is now called the Tandem NonStop Kernel. This change reflects Tandem’s current and future operating system enhancements that further enable open systems and application portability. The Sterling Software services to which NonStop NET/MASTER MS connects, formerly the product called NET/MASTER, is now referred to as the SOLVE management services.
New and Changed Information Section 7 Run-Time Error Handling No change. Section 8 Executing NCL Procedures The description of the default search path for NCL procedures has been updated. The subsection “How to Customize the NCL Procedure Search Path” is new. Section 9 Debugging an NCL Process This section discusses the new ON and OFF operands of the DEBUG SOURCE command. The method of assigning a default NCL ID is discussed, with a new table to show dependencies.
New and Changed Information Glossary Index The glossary has been expanded. The index has been expanded.
New and Changed Information (This page left intentionally blank) vi 106160 Tandem Computers Incorporated
Contents About This Manual xxvii Notation Conventions Section 1 xxxiii Introduction to NCL NCL and Major NonStop NET/MASTER MS Services Operator Control Services (OCS) 1-1 Edit Services 1-1 User ID Management Services (UMS) 1-2 Inter-NET/MASTER Connection (INMC) 1-2 Remote Operator Control (ROC) 1-2 Inter-System Routing (ISR) 1-2 1-1 Operations Available Through NCL 1-3 Accessing Data in User Databases (UDBs) 1-3 Automating Operations 1-4 Communicating With NonStop NET/MASTER MS Users and Terminals 1
Contents Section 3 An NCL Tutorial Before You Start 3-2 Getting Started With NCL Procedures 3-4 Your First NCL Procedure—HELLO1 3-4 Features of HELLO1 3-18 The HELLO2 NCL Procedure 3-19 Features of HELLO2 3-19 The HELLO3 NCL Procedure 3-20 Features of HELLO3 3-21 Getting Started With Functions 3-22 The BUILTIN1 NCL Procedure 3-22 Features of BUILTIN1 3-22 The BUILTIN2 NCL Procedure 3-23 Features of BUILTIN2 3-23 The USERW1 NCL Procedure 3-24 Features of USERW1 3-24 The USERW2 NCL Procedure 3-26 Features
Contents Writing NCL Procedures 4-12 Creating and Modifying an NCL Procedure Deleting an NCL Procedure 4-12 NCL Procedure Size 4-13 Performing a Test Compilation 4-13 NCL Procedure Libraries 4-15 Source Files and Object Files 4-15 System Procedure Libraries and Files User Procedure Libraries 4-18 4-12 4-15 Displaying Information About NCL Procedures 4-22 Displaying the Names of NCL Procedures 4-22 Displaying the Contents of NCL Procedures 4-24 Section 5 Controlling Execution Flow Single and Repetitive
Contents Section 6 Procedures and Functions Introducing NCL Procedures and Functions 6-1 Built-in Functions 6-2 External Procedures and External, User-Written Functions 6-6 Internal Procedures and Internal, User-Written Functions 6-6 Declaring Procedures and User-Written Functions 6-9 Explicit Declaration 6-9 Implicit Declaration—Procedures Only 6-11 Terminating Execution of the Current Procedure or Function 6-13 The END Statement—Procedures Only 6-13 The EXIT Statement—Procedures Only 6-14 The RETURN Sta
Contents Scope and Error Handling 7-16 The Scope of Core Statements 7-16 Scope and Replacing an Error Handler 7-17 Scope and Searching for an Error Handler 7-18 Scope and Recovering From an Error 7-19 Scope and Sharing Variables 7-20 Scope and Releasing an Error Handler 7-20 System Variables Containing Error Information Using the &SYSMSG Variable 7-21 7-22 System-Defined Error Handlers for Specific Conditions The ARITH_ERROR Error Handler 7-24 The FILE_ERROR Error Handler 7-24 The FLUSH_ERROR Error Hand
Contents Factors Affecting NCL Procedure Location 8-8 The Active, Retain, and Pend-Unload Lists 8-8 The Default Search Path 8-10 How to Customize the NCL Procedure Search Path 8-11 Preloading and Unloading 8-12 Sharing NCL Procedures 8-13 Test Mode 8-14 How NCL Procedure Location Factors Interact 8-15 The NCL Process Identifier (NCL ID) 8-16 Displaying Information About NCL Processes 8-17 Displaying the Current Status of NCL Processes Displaying Preloaded NCL Procedures 8-18 8-17 Controlling NCL Proces
Contents Examples Used to Illustrate DEBUG Commands 9-13 Purpose of the ZEX0902N NCL Procedure 9-13 Source Code of the ZEX0902N NCL Procedure 9-13 Output of the ZEX0902N NCL Process 9-15 Purpose of the ZEX0903N NCL Procedure 9-16 Source Code of the ZEX0903N NCL Procedure 9-16 Output of the ZEX0903N NCL Process 9-16 Starting a Single Debug Session 9-17 Targeting a Single NCL Process 9-17 Targeting NCL Processes by Execution State 9-18 Targeting NCL Processes in a Specific Window 9-22 Targeting a Specific Us
Contents Debugging an NCL Process From Start to Finish 9-60 Purpose of the NCL Procedure 9-60 Source Code of the NCL Procedure 9-60 Expected Output of the NCL Process 9-62 Current Output of the NCL Process 9-63 Step-by-Step Debugging of the NCL Process 9-65 Another Solution for the NCL Process 9-82 Section 10 Working With Mapping Services Components in Mapping Services Processing 10-2 Maps 10-2 Mapped Data Object (MDO) Variables 10-2 NCL Procedures 10-3 Example of Mapping Services Processing 10-3 The Stru
Contents User-Defined Maps 11-28 Why You Would Create a User-Defined Map 11-28 Creating a User-Defined Map 11-29 Using a User-Defined Map 11-35 Considerations for User-Defined Maps 11-40 Section 12 Working With Files Enscribe File Structures and NCL 12-2 Enscribe File Structures Supported by NCL Structured Enscribe Files 12-3 Edit Files 12-5 Guardian Processes 12-6 12-2 User Databases (UDBs) 12-6 Single UDBs 12-6 UDB Pairs 12-6 Creating a UDB 12-8 Creating a Single UDB 12-8 Creating the Files in a UDB P
Contents Setting UDB Characteristics 12-38 Specifying the Current UDB Identifier 12-38 Specifying the Current Record Structure 12-41 Specifying How to Handle the Record Key 12-41 Specifying the Current Record Key 12-42 Closing a UDB or UDB Pair for Access by NCL 12-42 Working With Entry-Sequenced Files 12-43 Creating the File 12-43 Opening the File for Access by NonStop NET/MASTER MS Opening the File for Access by NCL 12-44 Adding a Record 12-44 Getting a Record 12-48 Examples of Working With Entry-Seque
Contents Section 13 Interaction With Users and Terminals Displaying Text on the OCS Command Input Line Delaying Execution for a Specified Time Pausing for Operator Input 13-2 13-4 13-5 Writing a Message to a Terminal 13-6 Defining and Using Action Function Keys 13-8 Section 14 Working With Panels Panel Design Guidelines 14-2 Components in Panel Processing 14-3 NCL Procedures 14-3 Panel Description Files 14-3 The Structure of a Panel Description File 14-5 The Control Part of a Panel Description Fi
Contents Defining Field Characters in a Panel Description File 14-28 Standard, Predefined Field Characters 14-28 Defining Alternative Standard Field Characters 14-29 Extent of a Field Character 14-29 Specifying Display Attributes 14-30 Example of Input and Output fields 14-32 Specifying Output Padding and Justification 14-36 Specifying Input Padding and Justification 14-42 Defining Edit Rules for Input Fields 14-46 Defining Hexadecimal Field Characters 14-46 Dynamically Altering Panel Design 14-47 Defining
Contents Obtaining Input From a Panel 14-61 Obtaining Data in Input Field Variables 14-61 Controlling Function Key Interception and Translation 14-61 Handling Internal Validation Errors 14-67 Internal Validation Facilities 14-68 Automatic Internal Validation 14-69 Advanced Internal Validation 14-69 Discovering Which Input Fields Have Changed 14-70 Controlling Input Field Initialization 14-70 Controlling Input Field Formats 14-71 Controlling Output Field Attributes 14-71 Handling Input From Asynchronous Pan
Contents Controlling Access to a Server Class by NCL 15-11 System Variables Set by PSEND Verbs 15-11 Return Codes in &SYS.PSEND.
Contents Sending a Message Between NCL Processes, Using the WRITE Verb Sending Text 16-44 Sending Ordinary Variables 16-50 Sending MDO Variables 16-54 Sending a Message to an NCL Process When it Is Started Specifying Variables 16-59 Specifying the Environment 16-60 Synchronizing Execution 16-60 Example 16-60 16-44 16-59 Executing Persistent NCL Processes 16-64 Using the RESTART Operand in the START Verb 16-64 Number of Restarts in Persistent NCL 16-64 Persistent Versus Nonstop NCL Processes 16-64 Secti
Contents Section 18 Advanced NCL Programming Accessing the User ID Management Services (UMS) Database System Variables Set by SECCALL Verbs 18-2 Adding a Record 18-3 Changing a Record 18-8 Checking Logon Capability 18-11 Deleting a Record 18-12 Getting a Record 18-12 Updating a Record 18-15 Communicating With a Security Exit 18-16 18-1 Altering NCL Process Execution 18-17 Syntax of the CONTROL Verb 18-17 Sharing the CONTROL Environment 18-17 Synchronizing Access to Resources 18-18 Resources 18-18 Resourc
Contents Figure 10-3. Partial Structure of an Element in an MDO Variable Figure 10-4. Part of the Hierarchy of $MSG Figure 11-1. The Map $NCL 11-4 Figure 11-2. The Map $MSG 11-6 Figure 11-3. The Map $SEC 11-24 Figure 12-1. Record in a Structured Key-Sequenced Enscribe File Figure 12-2. Record Structure in an Entry-Sequenced File Figure 12-3. Records in an Entry-Sequenced File Figure 12-4. Record Structure in a Key-Sequenced File Figure 12-5.
Contents Figure 16-3. Environmental Hierarchy for a Real User 16-10 Figure 16-4. Flow of Commands and Results From OCS Figure 16-5. Flow of Commands and Results From NCL Under OCS Figure 16-6. Environmental Hierarchy for a Virtual User Figure 16-7. Using CMD in the Current Execution Environment Figure 16-8. Using CMD in the Primary Processing Environment Under OCS 16-20 Figure 16-9. Using INTCMD to Execute a Command 16-14 16-16 16-19 16-22 Figure 16-10.
Contents Table 10-3. Verbs That Can Use an MDO Variable After the Variable Is Created 10-31 Table 11-1. Verbs Used With Maps and MDO Variables Table 11-2. Standard Maps Table 11-3. Maps Referred to by Verbs Table 11-4. SPI Tokens Converted to External Form in an MDO Variable 11-16 Table 11-5. Considerations for TACL Data Types Table 11-6. Considerations for TYPE Clause Data Types Table 11-7. Considerations for PICTURE Clause Data Types Table 12-1.
Contents xxvi Table 15-1. Verbs and NonStop NET/MASTER MS Commands Used With Pathway Server Classes 15-1 Table 15-2. System Variables Set by PSEND Verbs Table 15-3. PSEND Verb Return Codes in &SYS.PSEND.RC Table 16-1. Core Statement, Verb, and NonStop NET/MASTER MS Commands Used to Initiate Processing in an Environment 16-1 Table 16-2. Verbs and NonStop NET/MASTER MS Command Used to Handle Messages in an Environment 16-2 Table 16-3. Virtual Users Table 16-4.
About This Manual The NonStop NET/MASTER Network Control Language (NCL) is part of NonStop NET/MASTER Management Services (MS). The NonStop NET/MASTER NCL Programmer's Guide is designed to give you a complete overview of NCL. The manual describes NCL concepts and terms. It discusses how to create and execute NCL procedures and functions, and how to control NCL processes. It explains how to use NCL core statements, verbs, built-in functions, variables, expressions, and operators.
About This Manual How This Manual Is Organized Section 5, “Controlling Execution Flow,” discusses the NCL core statements used to control single and repetitive execution, conditional execution, and explicit branching in an NCL procedure or function. Section 6, “Procedures and Functions,” describes the different types of NCL procedures and functions, how to declare them, how to terminate execution, how to pass parameters, how to share variables, and how to call them.
About This Manual How to Use This Manual The index provides an alphabetic access point to significant terms and topics discussed in this manual. Hint Throughout this manual, there are many helpful hints that suggest how to improve the performance of an NCL process.
About This Manual Where to Go for More Information The NonStop NET/MASTER NCL Reference Manual Before reading Sections 10 through 16 in the NonStop NET/MASTER NCL Programmer’s Guide, it is recommended that you read the sections discussing compiler operation, variables, expressions and operators, and verb syntax and variable access methods in the NonStop NET/MASTER NCL Reference Manual. The NonStop NET/MASTER NCL Programmer’s Guide is the companion manual to the NonStop NET/MASTER NCL Reference Manual.
About This Manual Documentation Road Map Figure 1.
About This Manual Your Comments Invited Your Comments Invited xxxii After you have had a chance to use this manual, please take a moment to fill out the Reader Comment Card and send it to us. The Reader Comment Card is located at the back of the printed manual and as a separate file in the CD Read Document List. You can fax the card to us at (408) 285-6660 or mail the card by using the business reply address on the back of the card in the printed manual.
Notation Conventions General Syntax Notation UPPERCASE LETTERS The following list summarizes the notation conventions for syntax presentation in this manual. Uppercase letters indicate keywords and reserved words; enter these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH lowercase italic letters Lowercase italic letters indicate variable items that you supply. Items not enclosed in brackets are required.
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: M address-1 [ , 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...
1 Introduction to NCL The NonStop NET/MASTER Network Control Language (NCL) is a structured, highlevel language supplied with NonStop NET/MASTER Management Services (MS) and integrated with other NonStop NET/MASTER MS services. This section introduces NCL. It explains where NCL fits in with major NonStop NET/MASTER MS services and describes some of the operations available through NCL.
Introduction to NCL NCL and Major NonStop NET/MASTER MS Services User ID Management Services (UMS) UMS is the NonStop NET/MASTER MS security service that enables the definition of authorized NonStop NET/MASTER MS users and their associated functions and privileges. UMS gives you the authority to use services of NonStop NET/MASTER MS. It enables, for example, access to OCS and Edit Services.
Introduction to NCL Operations Available Through NCL EMSPROC procedure or you can use an example EMSPROC procedure supplied with NonStop NET/MASTER MS to gather EMS messages. LOGPROC and MSGPROC are two other NCL procedures used to intercept and process system-level message flows. For more information on ISR, EMSPROC, and LOGPROC, refer to the NonStop NET/MASTER MS System Management Guide. For more information on MSGPROC, refer to the NonStop NET/MASTER MS Operator’s Guide.
Introduction to NCL Operations Available Through NCL Automating Operations NCL contains constructs that allow NCL processes to make logical decisions based on the analysis of system and network information. This feature of NCL, coupled with the ability of an NCL process to monitor and control system and network activity and to react automatically to events, allows you to automate many NonStop NET/MASTER MS operations. For example, an NCL process can monitor the status of terminals.
Introduction to NCL Operations Available Through NCL Creating Customized NonStop NET/MASTER MS Commands Displaying Panels You execute NonStop NET/MASTER MS commands by typing them at the OCS command input line. After writing an NCL procedure, you can usually execute it by simply typing its name at the OCS command input line—effectively creating a customized command. A panel is a formatted screen display that overlays an entire screen window. NCL processes display panels by using panel description files.
Introduction to NCL Operations Available Through NCL MSGPROC, which is an NCL procedure that intercepts and processes messages destined for an OCS window. System-level NCL procedures can edit, discard, act upon, or forward an event message. A system-level NCL procedure can execute another NCL procedure to deal with a certain message, if further processing is required. Using NCL, you can also generate an event message to send to the destination you specify, such as EMSPROC or $0.
2 NCL Summary This section provides an overview of the NonStop NET/MASTER Network Control Language (NCL). It summarizes the main features and elements of NCL. It briefly describes every core statement and verb. Language Features This subsection describes the important general characteristics of NCL: Context and meaning Abbreviations Block structure Scope Context and Meaning NCL is a contextual language.
NCL Summary Language Features Table 2-2 shows some examples of keywords used in verbs. Table 2-2.
NCL Summary Language Features Table 2-3 shows some examples that illustrate where alphabetic characters—and therefore their case—are not significant in the current context. Table 2-3. Alphabetic Characters and the Current Context What You Type Characters Not Important WRITE DATA=GOOD MORNING After DATA= in the WRITE verb; all letters remain in uppercase. After the SAY core statement; the first letter G remains in uppercase and all other letters remain in lowercase.
NCL Summary Language Features Table 2-4 shows some examples that illustrate this point. Table 2-4. Nonalphanumeric Characters and the Current Context What You Type Meaning of Nonalphanumeric Characters &A=SUBSTR(ABC,1,2) &B=((1+2)*&Z) &SYS.DATE.DAY &C=&D*3.5 /* Good morning */ &E=&F*&G SHRVARS=(&A*,&B*) CALL PROC1(A,B,C) SAY "Hi: I’m here" LABEL1: SAY Hi;SAY Hi again SAY "Hi; I’m here" Parentheses delimit arguments in a built-in function. Parentheses determine order of precedence in an expression.
NCL Summary Language Features You can use these language constructs to design, debug, and integrate NCL procedures in a structured way. You can design a small module of code and debug it by using the DEBUG commands. In addition, you can progressively integrate modules that are known to be error-free. The DEBUG commands are discussed in detail in Section 9, “Debugging an NCL Process.” Scope Everything that NCL does, it does within boundaries.
NCL Summary Language Elements For example, labels in one procedure or function are visible from another procedure or function, but it is illegal to invoke a procedure or function with a GOTO or GOSUB statement because the labels are not in the scope of these core statements. It is illegal to jump into a DO loop. For more on the scope of labels, see Section 4, “Initial NCL Procedure Development,” Section 5, “Controlling Execution Flow,” and Section 6, “Procedures and Functions.
NCL Summary Language Elements Table 2-5. Summary of Core Statements Core Statement Description Assignment statement CALL CMD Assigns a value to a variable. DO END EXIT FLUSH FUNCTION GOSUB GOTO IF ITERATE LEAVE NOP ON PROCEDURE RESUME RETRY RETSUB RETURN REVERT SAY SELECT SIGNAL SIGNAL LABEL Calls an NCL procedure. Issues a NonStop NET/MASTER MS command for execution in the current execution environment. Executes a group of statements once or repetitively.
NCL Summary Language Elements PROCEDURE and FUNCTION Core Statements The PROCEDURE and FUNCTION core statements are used to structure blocks of code within an NCL procedure. PROCEDURE explicitly declares a procedure. NCL procedures perform a task but do not have to return a result to the calling procedure or function. They can return a return code, which is placed in the system variable &SYS.RETCODE. They can also return variables to the calling procedure or function.
NCL Summary Language Elements DO, ITERATE, and LEAVE Core Statements The DO core statement delineates a block of statements to execute as a group, either once only (as a DO group) or repetitively (as a DO loop). The ITERATE core statement executes the next iteration of a DO loop. The LEAVE core statement terminates a DO loop. IF and SELECT Core Statements The IF and SELECT core statements provide conditional execution of a statement, depending on the evaluation of a test condition.
NCL Summary Language Elements Assignment Statement, CMD, NOP, and SAY Core Statements Other core statements, which do not change the structure or flow of an NCL procedure, are: the assignment statement, CMD, NOP, and SAY. The assignment statement explicitly assigns a value to a variable. Compare the assignment statement to the ASSIGN verb, described later in this section. The CMD core statement executes a NonStop NET/MASTER MS command in the current execution environment.
NCL Summary Language Elements Table 2-6. Summary of Verbs (Page 1 of 3) Verb Description ASSIGN CMDLINE CNMALERT Manipulates multiple variables in a single operation. Writes the specified text to an OCS command input line. Sends a communications network management (CNM) record directly to the EMSPROC NCL procedure for processing. Clears all outstanding communications network management (CNM) reply data solicited by an NCL process.
NCL Summary Language Elements Table 2-6. Summary of Verbs (Page 2 of 3) Verb Description INTCLEAR Discards outstanding messages queued to a dependent processing environment. Executes a NonStop NET/MASTER MS command in the dependent processing environment of an NCL process. Propagates a message read using the INTREAD verb to the next higher processing environment and, optionally, changes its message text.
NCL Summary Language Elements Table 2-6. Summary of Verbs (Page 3 of 3) Verb Description SECCALL ADD Adds a new user ID definition record to the User ID Management Services (UMS) database. Changes the password and a restricted set of personal details of a user ID definition record in the User ID Management Services (UMS) database. Validates a user ID and password combination of a user ID definition record in the User ID Management Services (UMS) database.
NCL Summary Language Elements Verbs and Variables A key feature of most verbs is that they deal with data using variables. Verbs can split data and place the parts into variables. They can read variables to obtain data. They can change data in variables. Accordingly, many verb operands allow you to create and refer to multiple variables.
NCL Summary Language Elements DROP explicitly deletes (drops) multiple variables in a single operation. It is used in relation to variables used by panels and MDO variables. DROP does more than simply assign a null value to variables; it removes both the variable and its value from memory. EVENTTD Verb NCL processes can read the Event Management Service (EMS) EVENTTD database to obtain help text records.
NCL Summary Language Elements displays that overlay an entire screen window. They are used to present information to users and to gather information from users. Panel display is controlled from NCL processes. PANEL and PANELEND are the two verbs used to control panel display. PANEL displays a panel and PANELEND explicitly removes a panel from display. An NCL process can display many panels, one after another, according to the input received from a user or another NCL process.
NCL Summary Language Elements CNM* Verbs. Verbs that begin with CNM control the flow of IBM communications network management (CNM) messages. These are solicited or unsolicited network management messages conveying information about IBM Systems Network Architecture (SNA) objects. The CNMCLEAR verb clears all CNM messages destined for an NCL procedure. The CNMREAD verb reads the next CNM message destined for an NCL procedure. The CNMSEND verb sends data from an NCL procedure across a CNM interface.
NCL Summary Language Elements SECCALL Verbs NCL processes can access the User ID Management Services (UMS) database using the SECCALL verbs. There are many SECCALL verbs (SECCALL ADD, SECCALL CHECK, and so on.) These verbs allow you to add a new user to the UMS database, change, check, retrieve, and delete user ID records in the database, and to communicate with your own security exit if your installation is using one. LOCK Verb Cooperating NCL processes can lock resources using advisory locks.
NCL Summary Language Elements Note Variables The setting of the PARAM SWGUID command does not affect whether a user can switch from the current GUID to a new GUID within NonStop NET/MASTER MS. The setting determines whether switching occurs when a user interacts with a file or process external to NonStop NET/MASTER MS. Variables hold values that can change during the execution of an NCL process. You do not have to explicitly declare the variables you want to use in an NCL procedure or function.
NCL Summary Language Elements System variables are variables distributed with your NonStop NET/MASTER MS software that have the reserved stem of &SYS.. System variables hold systemmaintained information. This includes: Date and time Cursor position NCL information Operating system information Return codes for error handling Terminal hardware information Window information Operating system information All system variables are available for reading by an NCL process.
NCL Summary Language Elements Built-in Functions Built-in functions provide access to information that could otherwise require extensive coding to acquire. Like user-written functions, built-in functions are called from expressions. A built-in function performs operations on any arguments passed to it. It returns a result that can be used as part of further expression evaluation.
NCL Summary Language Elements (This page left intentionally blank) 2–22 106160 Tandem Computers Incorporated
3 An NCL Tutorial Perhaps the best way to learn how to use NCL is to write a couple of NCL procedures and execute them. This section guides you through the steps required to do so.
An NCL Tutorial Before You Start Before You Start Let us begin at the beginning. Before you can write anything in NCL, there are a couple of important things you should check: 1. You must be able to log on to your NonStop NET/MASTER Management Services (MS) system. You must have a user ID definition record in User ID Management Services (UMS). It must have a valid user ID and password. You must know how to log on to your NonStop NET/MASTER MS system.
An NCL Tutorial Before You Start 4. You must have a library, a user procedure library, in which to store your NCL source files when you create them. More than one user can use the same user procedure library. The name of your library is defined either by the PARAM command or in your user ID definition record. Refer to the NonStop NET/MASTER MS System Management Guide for information on PARAM commands and defining a user procedure library using UMS.
An NCL Tutorial Getting Started With NCL Procedures Getting Started With Here is a step-by-step example that shows you how to create, test compile, correct, and NCL Procedures execute your first NCL procedure. The name of the NCL procedure is HELLO1. When executed, this NCL procedure displays the following message in the OCS message display area: hello, world The HELLO1 NCL procedure introduces the language constructs of core statements, labels, and expressions.
An NCL Tutorial Getting Started With NCL Procedures Step 1 Select Edit Services from the NonStop NET/MASTER MS primary menu. Type 8 after the Select Option ===> prompt, as shown in the following screen, and then press the ENTER key: SYS1------- NonStop NET/MASTER MS T6581D30 - 31OCT94 : Primary Menu -------SYS1 Select Option ===> 8 2 8 E M S U X - Operator Control Services Edit Services Console Extras User ID Management Services System Support Services User Services Terminate Window.
An NCL Tutorial Getting Started With NCL Procedures Step 2 Type the file name of the new NCL procedure. This is also the name of a new TEDIT file. When you enter Edit Services, your cursor is positioned after the File Spec: prompt. Type the file name, HELLO1, after the File Spec: prompt, as shown in the following screen, and then press the ENTER key: ------------------------- Edit Services : Selection List ---------------------File Spec: HELLO1 Subvolume: $DATA9.
An NCL Tutorial Getting Started With NCL Procedures Step 3 Type the new NCL procedure into a TEDIT file, in uppercase and lowercase letters, as shown in the following screen: hello_world: PROCEDURE SAY "hello, world" END hello_world 1) $DATA9.MYNCLLIB.HELLO1 1/24 (BOF) (EOF) 1:79 Insert D30. BLOCK The screen is blank when you invoke TEDIT because the NCL procedure is initially an empty TEDIT file called HELLO1. As you type, your input is entered in the TEDIT file.
An NCL Tutorial Getting Started With NCL Procedures Step 4 Save the new NCL procedure and exit TEDIT. Press the F1 function key and then type EXIT at the Command: prompt, as shown in the following screen (you can also press the SHIFT/F16 function key combination to exit TEDIT): Command: EXIT SAY "hello, world" END hello_world 1) $DATA9.MYNCLLIB.HELLO1 1/24 (BOF) (EOF) 1:79 Insert D30. BLOCK When you press the F1 function key, the Command: prompt hides the top line of your new NCL procedure.
An NCL Tutorial Getting Started With NCL Procedures Step 5 Perform a test compilation of the new NCL procedure. Move the cursor before HELLO1 using the arrow keys or the TAB key, type the letter C, as shown in the following screen, and then press the ENTER key: ------------------------- Edit Services : Selection List ---------------------File Spec: Subvolume: $DATA9.
An NCL Tutorial Getting Started With NCL Procedures Step 6 Check for mistakes after the test compilation by looking at the message line that appears at the top of the Edit Services selection list screen, as shown in the following screen: ------------------------- Edit Services : Selection List ---------------------File Spec: Subvolume: $DATA9.
An NCL Tutorial Getting Started With NCL Procedures Step 7 Note If your test compilation in Step 6 was unsuccessful, you should proceed directly to Step 11. Exit Edit Services and return to the NonStop NET/MASTER MS primary menu by pressing the F3 function key. Step 8 Select Operator Control Services (OCS) from the NonStop NET/MASTER MS primary menu.
An NCL Tutorial Getting Started With NCL Procedures Step 9 Execute the HELLO1 NCL procedure. When you enter OCS, your cursor is positioned after the OCS command input line prompt (=>).
An NCL Tutorial Getting Started With NCL Procedures Step 10 Check the results from executing the HELLO1 NCL procedure. The results are displayed in the roll-delete message area of the OCS window, as shown in the following screen: (11:16) --------------------- OPERATOR CONTROL SERVICES ---------------------START HELLO1 hello, world NNM1005 START HELLO1 PROCESSING COMPLETE.
An NCL Tutorial Getting Started With NCL Procedures Step 11 Note This step follows Step 6 if your test compilation was unsuccessful. If you have just completed Step 10, you should go to the subsection “Features of HELLO1” later in this section.
An NCL Tutorial Getting Started With NCL Procedures Step 12 Examine the error list created by the test compilation of the NCL procedure to determine the cause of the error. Press the F11 function key to display the error list.
An NCL Tutorial Getting Started With NCL Procedures Step 13 Exit the Edit Services NCL compile report screen and return to the Edit Services selection list screen by pressing the F3 function key. Step 14 Select the HELLO1 NCL procedure for editing. Move the cursor before HELLO1 using the arrow keys or the TAB key, type the letter E, as shown in the following screen, and then press the ENTER key: ------------------------- Edit Services : Selection List ---------------------File Spec: Subvolume: $DATA9.
An NCL Tutorial Getting Started With NCL Procedures Step 15 Examine the NCL procedure and insert the missing closing quote (”) after the letter “d” in the word “world,” as shown in the following screen: hello_world: PROCEDURE SAY "hello, world" <-- Insert closing quote here END hello_world 1) $DATA9.MYNCLLIB.HELLO1 1/24 (BOF) (EOF) 1:79 Insert D30. BLOCK Step 16 Follow Steps 4 through 10 described earlier in this section: Step 4—save the NCL procedure and exit TEDIT.
An NCL Tutorial Getting Started With NCL Procedures Features of HELLO1 Now that you have successfully executed your first NCL procedure, it is instructive to look at some of its features. The File Name—HELLO1 HELLO1 is the name of a TEDIT file containing NCL statements. It is called the NCL procedure source file name. It is also the name of the external procedure you have just created. An external name is the name used by other source files to refer to an NCL procedure.
An NCL Tutorial Getting Started With NCL Procedures The HELLO2 NCL Procedure Now let us create another NCL procedure called HELLO2, as shown in the following listing: hello_world: PROCEDURE /* Displays "hello, world" on an OCS screen */ /* using the WRITE verb */ &1 = "hello," &2 = world WRITE DATA=&1 &2 END hello_world Follow the steps described earlier in this section to create, test compile, correct, and execute HELLO2.
An NCL Tutorial Getting Started With NCL Procedures The Unquoted String—world Quotes are not needed for “world.” It has only alphabetic characters. It is another type of lexical element called an unquoted string. The Assignment Statements HELLO2 has two assignment statements. An assignment statement assigns the value on the right side of an equal sign (=) to the variable on the left side of the equal sign.
An NCL Tutorial Getting Started With NCL Procedures Features of HELLO3 Here are some of the features of the NCL procedure HELLO3. Changing Message Appearance Using the WRITE Verb The WRITE verb can change the appearance of a message with keywords such as HLITE, COLOR, and INTENS and qualifiers such as BLINK, RED, and HIGH. By using these keywords and qualifiers with the WRITE verb, HELLO3 displays a red, blinking message in high intensity.
An NCL Tutorial Getting Started With Functions Getting Started With The examples in this section have focused on NCL procedures. This subsection Functions discusses functions. An NCL procedure is a sequence of NCL statements that performs a task and, optionally, returns a result. For example, an NCL procedure can display a message such as “hello, world” in various ways. Functions also perform tasks, but do so in a much more limited way than NCL procedures.
An NCL Tutorial Getting Started With Functions “hello, world.” The second parameter is a number, indicating the character at which to begin the extraction—1, in this case, means the first character of the string, which is the letter “h” in this example. The third parameter is also a number, indicating the number of characters to extract from the string—5, in this case, means five characters, which are the letters “h,” “e,” “l,” “l,” and “o” in this example.
An NCL Tutorial Getting Started With Functions The C2X Built-in Function The C2X built-in function converts any string to its hexadecimal equivalent. In BUILTIN2, the string “hello, world” is converted to its hexadecimal equivalent. The CENTER Built-in Function The CENTER built-in function centers a string of characters inside another string of characters. In BUILTIN2, the string of characters to center is “hello, world.
An NCL Tutorial Getting Started With Functions CUBE executes the NCL statements in the function declaration. The purpose of CUBE is to produce the cube of a number. There is no built-in function that performs this task. The CUBE: Label You must name a user-written function with a label. “CUBE:” at the beginning of the function is a label. The label is used to call the function. The FUNCTION Core Statement FUNCTION marks the beginning of the user-written function.
An NCL Tutorial Getting Started With Functions The USERW2 NCL Procedure The CUBE user-written function produces the cube of the number 2. With some minor changes, however, we can create a much more useful function.
An NCL Tutorial Getting Started With Functions The following screen shows the result of executing the USERW2 NCL procedure three times in the OCS message display area: (14:45) --------------------- OPERATOR CONTROL SERVICES ---------------------START USERW2 5 Cube of 5 is: 125 NNM1005 START USERW2 PROCESSING COMPLETE. NCLID 008503 START USERW2 11 Cube of 11 is: 1331 NNM1005 START USERW2 PROCESSING COMPLETE. NCLID 008504 START USERW2 17 Cube of 17 is: 4913 NNM1005 START USERW2 PROCESSING COMPLETE.
An NCL Tutorial Writing a MSGPROC NCL Procedure Writing a MSGPROC NCL Procedure One of the most important features of NCL is its ability to intercept and process message flows that travel to, from, and throughout NonStop NET/MASTER MS. NonStop NET/MASTER MS is distributed with examples of the three system-level NCL procedures that handle event messages: EMSPROC, which is an NCL procedure that intercepts and processes Event Management Services (EMS) messages.
An NCL Tutorial Writing a MSGPROC NCL Procedure 3. Note The MESSGEN NCL Procedure Create, test compile, correct, and execute the MSGPROC NCL procedure. Ensure that you use the PROFILE MSGPROC command to execute MSGPROC because NonStop NET/MASTER MS displays an error if you attempt to execute MSGPROC using either the START or EXEC command. You must use the PROFILE MSGPROC command because MSGPROC is part of your OCS profile.
An NCL Tutorial Writing a MSGPROC NCL Procedure Follow the steps described earlier in this section to create, test compile, correct, and execute MESSGEN.
An NCL Tutorial Writing a MSGPROC NCL Procedure Note Your user ID may be different from the user ID, NNMUSER, shown in this example. The DELAY Verb DELAY temporarily suspends execution of an NCL process. In MESSGEN, the NCL process is suspended for 10 seconds. The END Core Statements The first END core statement ends the DO loop. The last END core statement ends the NCL procedure.
An NCL Tutorial Writing a MSGPROC NCL Procedure After you install the procedure, you can check the results.
An NCL Tutorial Writing a MSGPROC NCL Procedure The MSGPROC NCL procedure is correctly installed if you see the display highlighted in the following screen: (13:11) --------------------- OPERATOR CONTROL SERVICES ---------------------PROFILE NNM0381 USERID: NNMUSER TERMINAL-ID: #9246528 NNM0382 NCL PROCEDURE LIBRARY ID: $DATA9.MYNCLLIB NNM0383 USERID HAS MONITOR STATUS. NNM0384 AUTOHOLD SETTING IS ON AUTO. NNM0385 AUTHORITY LEVEL IS 2, MSGPROC MSGPROC ACTIVE.
An NCL Tutorial Writing a MSGPROC NCL Procedure Leave the message unchanged and forward it on using the MSGCONT verb. The unchanged message is displayed at the OCS window. The &WORD&(SYS.VARCNT) Complex, Nested Variable The &WORD&(SYS.VARCNT) is a complex, nested variable. A complex variable is a variable with more than one ampersand (&). A nested variable is a variable that begins with an ampersand and an opening parenthesis and terminates with a closing parenthesis (&, (, and )).
An NCL Tutorial What to Do Next The preceding screen shows that the MSGPROC NCL procedure does the following: Deletes the “Hello message” message—it begins with “Hello” but does not end with your user ID. Modifies the attributes of the “Hello message NNMUSER” message—it begins with “Hello” and ends with your user ID—and forwards it on to the OCS window. Note Your user ID may be different from the user ID, NNMUSER, shown in this example.
An NCL Tutorial What to Do Next (This page left intentionally blank) 3–36 106160 Tandem Computers Incorporated
4 Initial NCL Procedure Development This section discusses the fundamentals of NCL procedure development. The section: Outlines the structure of an NCL procedure Summarizes tasks associated with writing an NCL procedure Discusses NCL procedure libraries for source files and object files Explains how to display information about NCL procedures This section does not discuss how to execute a procedure. This is covered in Section 8, “Executing NCL Procedures.
Initial NCL Procedure Development The Structure of an NCL Procedure The following example shows how you can use the line continuation character to split this long line into multiple lines: WRITE ALARM=YES, COLOR=PINK, HLITE=BLINK, NRD=YES, DATA=&message The following example splits a quoted string over more than one line: CMD "UNIT DEFINE=ZNNMU SESSION=ZNNMS MODE=PRIMARY", "DEVICE=$ZNNM.SUBVOL1.
Initial NCL Procedure Development The Structure of an NCL Procedure Statements Lines in an NCL procedure can contain one or more statements. Statements are instructions that are interpreted by NCL according to the initial keyword. There is a clear distinction in NCL between statements, core statements and verbs. The term statement refers to lines of code within an NCL procedure. Core statements and verbs are particular types of statements.
Initial NCL Procedure Development The Structure of an NCL Procedure Comments A comment is a nonexecutable statement. You can use comments to describe what an NCL procedure does at each logical step. Comments begin with a comment delimiter (/*) and end with a comment delimiter (*/). (The final comment delimiter (*/) is also called a comment terminator.
Initial NCL Procedure Development The Structure of an NCL Procedure You cannot split comment delimiters between lines. Comment delimiters split across line boundaries are not recognized as comment delimiters. The following example illustrates incorrect use of a comment terminator because it is split between two lines: /* This is an example of an invalid comment because its comment terminator is split between two lines.* / Comments are not recognized within quoted strings.
Initial NCL Procedure Development The Structure of an NCL Procedure Table 4-1 lists the characters that you can use in labels. Table 4-1. Valid Label Characters Character Name Restrictions A-Z a-z 0-9 . _ @ # $ ""'' Letters Digits Period Underscore At sign Number sign Dollar sign Quotes Other characters : Varies Colon Lowercase letters are converted to uppercase letters. None. None. None. None. None. None. Quotes must match and must surround all other characters except the colon.
Initial NCL Procedure Development The Structure of an NCL Procedure Labels are case-insensitive. This means all lowercase alphabetic characters in labels are translated to uppercase. This includes quoted labels. The following labels are interpreted by NCL to be the same: abc: "abc": 'abc': ABC: "ABC": 'ABC': You can prefix a statement with one or more labels. These label combinations can be on different lines or the same line. You do not have to follow a label by a statement terminator.
Initial NCL Procedure Development The Structure of an NCL Procedure Some core statements, such as PROCEDURE and FUNCTION, require at least one label. Keywords such as ELSE and WHEN prohibit labels. Refer to the NonStop NET/MASTER NCL Reference Manual to check whether a particular statement or keyword requires or prohibits a label. You can specify a label on a nested statement.
Initial NCL Procedure Development The Structure of an NCL Procedure The example shows: How you can target the same statement using different labels. task2: and task3: are different labels that target the same subroutine. How you can dynamically generate the label which you want to target. The example uses a DO loop and the (implicit) string operator (||) to do this. Where you can position labels. task1:, task2:, and task3: are on different lines. task4:, task5:, and task6: are on the same line.
Initial NCL Procedure Development The Structure of an NCL Procedure The following example shows an NCL procedure that uses many of the core statements that can use labels: zex0402n: PROCEDURE /* Procedure containing many labels */ SIGNAL_LABEL: &a = 21 DO_UNTIL_LABEL: DO UNTIL ( &a = 0 ) &a = &a - 1 IF even_func_label( &a ) THEN ITERATE do_until_label SAY &a is an odd number GOSUB gosub_label IF &a = 11 THEN LEAVE do_until_label END do_until_label EXIT GOSUB_LABEL: GOTO goto_label_&a IF &signal_label_used
Initial NCL Procedure Development The Structure of an NCL Procedure The following screen shows the results of executing the procedure: (10:21) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0402N 19 is an odd number 17 is an odd number 19 is an odd number 17 is an odd number 15 is an odd number ... and only appears once! 13 is an odd number ... and only appears once! 11 is an odd number ... and only appears once! NNM1005 START ZEX0402N PROCESSING COMPLETE.
Initial NCL Procedure Development Writing NCL Procedures LEAVE, and SIGNAL LABEL core statements. The name space for these labels is bound by the procedure or function in which the label occurs. Labels of these core statements do not have to be unique within a procedure or function and they can occur anywhere within the procedure or function. NCL uses different rules to search and find each type of label.
Initial NCL Procedure Development Writing NCL Procedures NCL Procedure Size There are no NCL features that limit the size of an NCL procedure. The size of an NCL procedure is restricted only by the physical limits of your system (memory capacity, disk capacity, and so on). Larger NCL procedures are slower to edit. For convenience, it is recommended that you keep your NCL procedures to a moderate size.
Initial NCL Procedure Development Writing NCL Procedures The following example, when compiled, generates many compilation errors: zex0403n: PROCEDURE /* This NCL procedure is executed when */ /* I select OCS from the primary menu.
Initial NCL Procedure Development NCL Procedure Libraries NCL Procedure Libraries NCL procedure libraries are subvolumes that store NCL procedures. An NCL procedure library can store source files, or object files, or both. An NCL procedure library may be a system procedure library or a user procedure library. This subsection explains the difference between source files and object files. It then discusses the difference between system procedure libraries and user procedure libraries.
Initial NCL Procedure Development NCL Procedure Libraries NCL procedures in the distribution procedure library are distributed as source files of NCL statements, not as object code. They are compiled automatically as required after a NonStop NET/MASTER MS system is operational. The object code created by executing NCL procedures in the distribution procedure library is kept in a file defined using the PARAM NCLDISTOBJ command.
Initial NCL Procedure Development NCL Procedure Libraries NonStop NET/MASTER MS upgrades do not affect NCL procedures in the customized procedure library. The object code created by executing NCL procedures in the customized procedure library is kept in a file defined using the PARAM NCLCUSTOBJ command. The following example uses the PARAM NCLCUSTOBJ command to define the name of this file as $DATA4.ZNNMNCO.NCLCOBJ: PARAM NCLCUSTOBJ=$DATA4.ZNNMNCO.
Initial NCL Procedure Development NCL Procedure Libraries You can use the SHOW PARAM command to display the results of this PARAM command, as the following screen shows: (09:54) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW PARAM NNM0605 CONFIG FILE=$DATA4.ZNNM.CONFIG NNM0605 PROCESSCHAR=Z NNM0605 INIT=INIT NNM0605 READY=READY NNM0605 SWGUID=YES NNM0605 DID=SYS1 NNM0605 NCLDISTSRC=$DATA4.ZNNMNDS NNM0605 NCLCUSTSRC=$DATA4.ZNNMNCS NNM0605 NCLDISTCODE=$DATA4.ZNNMNDO.
Initial NCL Procedure Development NCL Procedure Libraries The location of the source files belonging to a user is defined in the user ID definition record for that user. The field in User ID Management Services (UMS) that defines the location is NCL Library Subvol, as the following screen shows: NNMJN----------------------- UMS : User Attributes -----------------Page 2 of 5 Command ===> Function=BROWSE Authority Level .............. 2 (0 - 255) Multiple Signon Authority .... Y Password Expire ...........
Initial NCL Procedure Development NCL Procedure Libraries You can use the SHOW PARAM command to display the results of the PARAM NCLOBJLIB command, as the following screen shows: (10:22) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW PARAM NNM0605 CONFIG FILE=$DATA4.ZNNM.CONFIG NNM0605 PROCESSCHAR=Z NNM0605 INIT=INIT NNM0605 READY=READY NNM0605 SWGUID=YES NNM0605 DID=SYS1 NNM0605 NCLDISTSRC=$DATA4.ZNNMNDS NNM0605 NCLCUSTSRC=$DATA4.ZNNMNCS NNM0605 NCLDISTOBJ=$DATA4.ZNNMNDO.
Initial NCL Procedure Development NCL Procedure Libraries Defining the Location of the Object File for a User by Using UMS. Using this method to define the location of the object file for a user creates a private object file.
Initial NCL Procedure Development Displaying Information About NCL Procedures Displaying Information As you create and modify NCL procedures, you may want to display information About NCL Procedures about the disk files and their contents. This subsection explains how you do so from Edit Services and OCS. Displaying the Names of NCL Procedures From Edit Services, you do not need to do anything to display the names of NCL procedures in your user procedure library.
Initial NCL Procedure Development Displaying Information About NCL Procedures From OCS, you can use the SHOW FILEINFO command to display the names of NCL procedures in your user procedure library (and the names of files in other locations).
Initial NCL Procedure Development Displaying Information About NCL Procedures Note The SHOW FILEINFO command does not restrict the display of files by file type. (In this example, to stop displaying files beginning with C in $SYSTEM.SYSTEM, you can use either the CLEAR ALL or K ALL command to clear the messages queued to your OCS window.) Refer to the NonStop NET/MASTER MS Command Reference Manual for more information on the SHOW FILEINFO command.
Initial NCL Procedure Development Displaying Information About NCL Procedures The following command lists the contents of an NCL procedure called EPROC3: LIST EPROC3 The following screen shows some of the display after you enter the command from the OCS command input line: (06:24) --------------------- OPERATOR CONTROL SERVICES ---------------------LIST EPROC3 NNM1018 eproc3: PROCEDURE NNM1018 /* EMSPROC to filter and display messages from various NNM1018 /* subsystems.
Initial NCL Procedure Development Displaying Information About NCL Procedures You can specify the name of a procedure library using the ID operand of the LIST command. NonStop NET/MASTER MS attempts to list the contents of the file in the specified procedure library. The following command lists the contents of the INIT NCL procedure: LIST INIT ID=$DATA4.
5 Controlling Execution Flow Controlling execution flow refers to controlling the order in which the statements that make up an NCL procedure or function are executed. This section discusses the NCL core statements used to control: Single and repetitive execution (DO and END; ITERATE; and LEAVE) Conditional execution (IF; NOP; and SELECT) Explicit branching (GOSUB and RETSUB; SIGNAL LABEL; and GOTO) Table 5-1 summarizes the core statements discussed in this section. Table 5-1.
Controlling Execution Flow Single and Repetitive Execution Single and Repetitive The core statements that control the single and repetitive execution of a DO group are Execution listed here in order of discussion: DO and END ITERATE LEAVE Single Execution With the DO and END Statements The DO and END core statements, without counters or Boolean conditions, are used to delineate a DO group, that is, a sequence of statements bound by the DO and END core statements that is executed once only.
Controlling Execution Flow Single and Repetitive Execution The following screen shows the results of executing the procedure twice: (11:20) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0501N 1 First statement Second statement Third statement NNM1005 START ZEX0501N PROCESSING COMPLETE. NCLID 000021 START ZEX0501N Fourth statement Fifth statement Sixth statement NNM1005 START ZEX0501N PROCESSING COMPLETE.
Controlling Execution Flow Single and Repetitive Execution Using a Constant Expression. If the expression following the DO keyword is a constant, the DO loop executes the number of times specified by the constant.
Controlling Execution Flow Single and Repetitive Execution Using a Variable Expression. If the expression following the DO keyword is a variable, the DO loop executes the number of times specified by the variable. The following example shows an NCL procedure that uses a variable expression in a DO loop: zex0503n: PROCEDURE /* Variable expression in a DO loop */ DO &1 SAY COPIES("*",(2 * &1)) END END zex0503n This procedure draws a rectangle on the screen.
Controlling Execution Flow Single and Repetitive Execution Using a Control Variable to Control Repetitive Execution A DO loop that uses a control variable to execute a group of statements repetitively can optionally use the keywords TO, BY, and FOR. The following table summarizes the meaning of these keywords: Keyword Meaning TO BY Sets the termination value of the control variable in a repetitive DO loop. Sets the value by which to increment or decrement the control variable in a repetitive DO loop.
Controlling Execution Flow Single and Repetitive Execution expri specifies an expression that must evaluate to 0 or a positive integer. This gives an initial value to the control variable the first time through the loop.
Controlling Execution Flow Single and Repetitive Execution Note Since there is no condition that terminates the DO loop in this example, the DO loop executes to the maximum value of the system variable &SYS.LOOPCTL (the default value of this variable is 1000) and terminates with a LOOPING_ERROR run-time error. The &SYS.LOOPCTL system variable is discussed later in this section. The LOOPING_ERROR error handler is discussed in Section 7, “Run-Time Error Handling.
Controlling Execution Flow Single and Repetitive Execution The following screen shows the results of executing the procedure: (10:00) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0505N 5 1 2 3 4 5 The final value of &control is 6 NNM1005 START ZEX0505N PROCESSING COMPLETE.
Controlling Execution Flow Single and Repetitive Execution Note NCL assumes a positive value of 1 for the increment even when the starting value of the control variable is greater than the value after the TO keyword. In this case, the loop is not executed. If the number following the BY keyword is not an integer it may be inaccurate (if it is not exactly representable in the underlying binary floating point numeric format).
Controlling Execution Flow Single and Repetitive Execution Using a Control Variable With the FOR Keyword. The FOR keyword limits the number of repetitions of a DO loop regardless of the value of the control variable. The syntax of a DO loop that uses the FOR keyword with a control variable is the following: DO cvar = expri [ TO exprt ] [ BY exprb ] FOR exprf statement1 statement2 statement3 … END exprf specifies an expression that must evaluate to 0 or a positive integer.
Controlling Execution Flow Single and Repetitive Execution The following screen shows the results of executing the procedure: (10:54) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0507N 1 1.5 2 2.5 3 The final value of &control is 3.5 NNM1005 START ZEX0507N PROCESSING COMPLETE.
Controlling Execution Flow Single and Repetitive Execution exprw specifies an expression that must evaluate to 1 (TRUE) or 0 (FALSE). If the expression is true, the loop is reexecuted. If the expression is false, execution continues with the statement following the END statement.
Controlling Execution Flow Single and Repetitive Execution Repetitive Execution Using the UNTIL Keyword An UNTIL clause introduces an expression that is tested after each iteration of a DO loop. The syntax of a DO loop that uses the UNTIL keyword is the following: DO UNTIL expru statement1 statement2 statement3 … END expru specifies an expression that must evaluate to 1 (TRUE) or 0 (FALSE). If the expression is false, the loop is reexecuted.
Controlling Execution Flow Single and Repetitive Execution The following screen shows the results of executing the procedure: (11:33) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0509N 1 2 3 4 5 6 7 8 9 10 The final value of &number is 11 NNM1005 START ZEX0509N PROCESSING COMPLETE.
Controlling Execution Flow Single and Repetitive Execution The following example shows an NCL procedure that specifies both the WHILE and UNTIL keywords in a DO loop: zex0510n: PROCEDURE /* DO loop with the WHILE and UNTIL keywords */ &while = 1 &until = 1 DO WHILE &while < 10 UNTIL &until > 5 SAY "&while is "&while SAY "&until is "&until &while = &while + 1 &until = &until + 1 END SAY "The final value of &while is "&while SAY "The final value of &until is "&until END zex0510n This procedure executes a DO
Controlling Execution Flow Single and Repetitive Execution Combining Counters and Conditional Clauses You can combine counters and conditional clauses in a DO loop.
Controlling Execution Flow Single and Repetitive Execution In this example, the condition that terminates the DO loop is the evaluation of the FOR keyword—the loop executes five times only. Executing a Loop Forever The FOREVER keyword explicitly executes a DO loop until it is terminated by a condition such as failing a WHILE test or branching out of the loop.
Controlling Execution Flow Single and Repetitive Execution Controlling Runaway DO Loops The keyword FOREVER implies that a DO loop executes indefinitely. This is not so in practice. If there is no condition that terminates execution, the loop executes to the maximum value of the system variable &SYS.LOOPCTL (the default value of this variable is 1000). It is normal practice, however, to specify a condition to terminate the execution of a repetitive DO loop before the maximum value of &SYS.
Controlling Execution Flow Single and Repetitive Execution The following example shows an NCL procedure with a nested DO loop: zex0513n: PROCEDURE /* Nested DO loop */ DO 2 SAY OUTER LOOP DO &control = 1 to 5 SAY Inner loop pass &control END END END zex0513n This procedure has one outer loop, which is executed twice, and one nested (inner) loop, which is executed five times.
Controlling Execution Flow Single and Repetitive Execution Using Labels on a DO Statement You can specify one or more labels on a DO statement. The END statement that closes the DO can specify the label (or one of the labels if more than one) to allow the compiler to check statement nesting for you. Specifying labels can be helpful when you nest DO loops to ensure that you match the opening DO statement with the correct closing END statement.
Controlling Execution Flow Single and Repetitive Execution The following example shows an NCL procedure that uses the ITERATE core statement to iterate a DO loop: zex0515n: PROCEDURE /* Adds up numbers until total is greater than */ /* or equal to 50 */ &total = 0 DO UNTIL &total >= 50 SAY "Enter a number in the OCS command input line" CMDLINE "-GO ID="&SYS.
Controlling Execution Flow Single and Repetitive Execution The LEAVE Core Statement The LEAVE core statement immediately exits a DO loop. The LEAVE statement logically passes control to the statement immediately after the bottom (the END statement) of a DO loop. (It logically meets the condition that terminates the DO loop.
Controlling Execution Flow Single and Repetitive Execution The following screen shows the results of executing the procedure: (08:17) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0516N Enter a number in the OCS command input line |NM1060 PROCEDURE ZEX0516N NCLID 58 PAUSED You have entered 33 Enter a number in the OCS command input line |NM1060 PROCEDURE ZEX0516N NCLID 58 PAUSED You have entered 12 Enter a number in the OCS command input line |NM1060 PROCEDURE ZEX0516N NCLID
Controlling Execution Flow Conditional Execution Conditional Execution There are three core statements that control the conditional execution of a statement or a group of statements: IF SELECT NOP The IF Statement The IF core statement tests an expression. It allows NCL to make a two-way decision based on the outcome of the test. The options are introduced by the THEN and ELSE keywords.
Controlling Execution Flow Conditional Execution The following screen shows the results of executing the procedure twice: (07:15) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0517N YXYZ The answer is YES NNM1005 START ZEX0517N PROCESSING COMPLETE. NCLID 007020 START ZEX0517N The answer is NO NNM1005 START ZEX0517N PROCESSING COMPLETE.
Controlling Execution Flow Conditional Execution The following example shows an NCL procedure that uses the IF statement with the DO statement: zex0518n: PROCEDURE /* IF statement with DO */ &answer = N get_answer: DO UNTIL &answer = Y SAY "Enter answer in the OCS command input line (Y/N)" CMDLINE "-GO ID="&SYS.
Controlling Execution Flow Conditional Execution Using the IF Statement With the NOP Statement You must follow the THEN keyword by a statement. You cannot follow the THEN keyword by a null statement. However, you can use the NOP core statement to explicitly specify no action. The following example shows an NCL procedure that uses the IF statement with the NOP statement: zex0519n: PROCEDURE /* IF statement with NOP */ SAY "Enter 2 characters" CMDLINE "-GO ID="&SYS.
Controlling Execution Flow Conditional Execution The SELECT and END Statements The SELECT core statement tests an expression. It allows NCL to make a multiway decision based on the outcome of the test. The options are introduced by the WHEN and OTHERWISE keywords. The END statement closes the block of statements introduced by the SELECT keyword. The SELECT core statement has two forms. These are called the first and second forms of the SELECT statement.
Controlling Execution Flow Conditional Execution The following example shows an NCL procedure that uses the first form of the SELECT statement: zex0520n: PROCEDURE /* First form of SELECT */ /* Displays number of days in month */ IF TYPECHK(NUM,&1) = NUM AND, &1 >= 1 AND, &1 <= 12, THEN SELECT WHEN &1 = 2 THEN SAY "28 or 29 days" WHEN &1 = 4 OR, &1 = 6 OR, &1 = 9 OR, &1 = 11 THEN SAY 30 days OTHERWISE SAY 31 days END ELSE SAY "Enter month as a number: 1 through 12" END zex0520n This procedure returns the n
Controlling Execution Flow Conditional Execution The values entered are a null value (incorrectly), 1 (January), 2 (February), 4 (April), 11 (November), 0 (incorrectly), and ABC (incorrectly).
Controlling Execution Flow Conditional Execution The following screen shows the results of executing the procedure four times: (12:51) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0521N 123 First parameter is neither a nor b NNM1005 START ZEX0521N PROCESSING COMPLETE. NCLID 000101 START ZEX0521N XYZ First parameter is neither a nor b NNM1005 START ZEX0521N PROCESSING COMPLETE. NCLID 000102 START ZEX0521N A First parameter = a NNM1005 START ZEX0521N PROCESSING COMPLETE.
Controlling Execution Flow Conditional Execution The following screen shows the results of executing the procedure twice: (12:14) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0522N "abc" Value of &1 is abc SIMPLE SELECT 1st WHEN STRICT SELECT 2nd WHEN NNM1005 START ZEX0522N PROCESSING COMPLETE. NCLID 002013 START ZEX0522N " abc" Value of &1 is abc SIMPLE SELECT 1st WHEN STRICT SELECT 1st WHEN NNM1005 START ZEX0522N PROCESSING COMPLETE.
Controlling Execution Flow Conditional Execution The following example shows an NCL that uses the SELECT statement with the DO statement: zex0523n: PROCEDURE /* SELECT statement with the DO statement */ &size = 0 SAY "Enter size of rectangle (3-15)" CMDLINE "-GO ID="&SYS.
Controlling Execution Flow Explicit Branching The following screen shows the results of executing the procedure: (12:24) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0523N Enter size of rectangle (3-15) |NM1060 PROCEDURE ZEX0523N NCLID 2018 PAUSED ABC is rubbish Enter size of rectangle (3-15) |NM1060 PROCEDURE ZEX0523N NCLID 2018 PAUSED 1 is too small Enter size of rectangle (3-15) |NM1060 PROCEDURE ZEX0523N NCLID 2018 PAUSED 16 is too big Enter size of rectangle (3-15) |NM
Controlling Execution Flow Explicit Branching The following example shows an NCL procedure that uses the GOSUB and RETSUB statements: zex0524n: PROCEDURE /* GOSUB and RETSUB statements */ SAY "Initial value of &SYS.RETCODE is "&SYS.RETCODE DO &taskno = 1 to 5 GOSUB task&taskno SAY "Loop "&taskno" &SYS.RETCODE is "&SYS.RETCODE END SAY "Final value of &SYS.RETCODE is "&SYS.
Controlling Execution Flow Explicit Branching The SIGNAL LABEL Statement The SIGNAL LABEL core statement transfers execution control to the specified label. The target label is the one that follows the LABEL keyword. You cannot use the SIGNAL LABEL statement to transfer control to a label in an inactive block of statements, for example, a DO group or a DO loop where the opening DO statement has not been executed. The target label can be a constant or an expression.
Controlling Execution Flow Explicit Branching The following screen shows the results of executing the procedure twice: (12:34) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0525N Begin procedure Exit procedure normally NNM1005 START ZEX0525N PROCESSING COMPLETE. NCLID 002022 START ZEX0525N Y Begin procedure Do error processing Exit procedure after error processing NNM1005 START ZEX0525N PROCESSING COMPLETE.
Controlling Execution Flow Explicit Branching Label Searching This subsection discusses how the GOTO, GOSUB, and SIGNAL LABEL core statements search for labels. It outlines the search rules. It explains how to limit a GOTO and GOSUB search with the LIMIT keyword. It explains how to use the MATCH keyword on GOTO and GOSUB to compare labels during a search.
Controlling Execution Flow Explicit Branching If NCL does not find a matching label, its action depends on the type of label it is. If the label is a constant, an error is raised during compilation. If the label is an expression, the GOTO, GOSUB, or SIGNAL LABEL statement is treated as a NOP core statement (the NOP statement performs no action). Execution continues with the statement after the GOTO, GOSUB, or SIGNAL LABEL statement.
Controlling Execution Flow Explicit Branching The following example shows an NCL procedure that uses the LIMIT keyword to limit a GOSUB search: zex0527n: PROCEDURE /* Limiting a GOSUB search */ SAY "Initial value of &SYS.RETCODE is "&SYS.RETCODE DO &taskno = 1 to 5 GOSUB task&taskno LIMIT task3 SAY "Loop "&taskno" &SYS.RETCODE is "&SYS.RETCODE END SAY "Final value of &SYS.RETCODE is "&SYS.
Controlling Execution Flow Explicit Branching Matching Labels—the GOTO and GOSUB Statements The MATCH keyword after a GOTO or GOSUB statement specifies the method of comparison you want performed between the label for which the GOTO or GOSUB is searching and the labels it encounters. The default method of comparison is for an exact match. (Remember that alphabetic characters are case-insensitive.) The following table lists the values that can follow the MATCH keyword. These values must be constant.
6 Procedures and Functions This section discusses NCL procedures and functions.
Procedures and Functions Introducing NCL Procedures and Functions Built-in Functions A built-in function is a function distributed with your NonStop NET/MASTER Management Services (MS) system. These functions are designed to return information that may otherwise require extensive coding to acquire.
Procedures and Functions Introducing NCL Procedures and Functions The following screen shows the results of executing the procedure: (09:58) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0601N Default date is: 29 AUG 1994 Date 1 is: 94.241 Date 2 is: MON 29-AUG-1994 Date 3 is: 29-AUG-1994 Date 4 is: 29/08/94 Date 5 is: 08/29/94 Date 6 is: 94/08/29 Date 7 is: 940829 Date 8 is: 19940829 Date 9 is: 728168 Time A is: 35899.242885 Time C is: 9.
Procedures and Functions Introducing NCL Procedures and Functions If you do pass a parameter to the DATE built-in function, you must pass only one parameter and it must be a parameter that the built-in function recognizes.
Procedures and Functions Introducing NCL Procedures and Functions The LENGTH built-in function provides the length of the data contained in &A. The length is used as the starting position from which to extract the substring from the data in &B. The result of executing this procedure is the following: 345 The following example uses the ABBREV, SPACE, and UPPER built-in functions: zex0603n: PROCEDURE NOFOLD /* ABBREV, SPACE, and UPPER built-in functions */ /* Check first character of &SYS.
Procedures and Functions Introducing NCL Procedures and Functions Note External Procedures and External, User-Written Functions Be sure to match opening parentheses (() with closing parentheses ()) and to position commas correctly when nesting built-in functions. External procedures and external, user-written functions are separate, self-contained, source files of NCL statements. (An external function is called a user-written function because it is written by you and not distributed as part of NCL.
Procedures and Functions Introducing NCL Procedures and Functions Figure 6-2 shows the structure of an internal function. The name of the function is given by the label, TOP_LEVEL_F, before the FUNCTION core statement. The END core statement explicitly terminates the declaration of the function. The NCL statements between the FUNCTION and END statements form the body of the function. Figure 6-2.
Procedures and Functions Introducing NCL Procedures and Functions Figure 6-3 shows the structure of some nested internal procedures and functions. The name of the top-level internal procedure is TOP_LEVEL_P. There are two nested procedures: LEVEL1_P1 and LEVEL1_P2. There is one nested function: LEVEL2_F. Figure 6-3.
Procedures and Functions Declaring Procedures and User-Written Functions Declaring Procedures You can declare both procedures and user-written functions explicitly but you can and User-Written declare only procedures implicitly. This subsection discusses how to begin and Functions terminate a procedure and function declaration. It discusses the following core statements: END FUNCTION PROCEDURE Explicit Declaration The PROCEDURE and FUNCTION core statements begin an explicit declaration.
Procedures and Functions Declaring Procedures and User-Written Functions The following screen shows the results of executing the procedure: (13:54) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0604N PROFILE MONMSG=NO PROFILE UNSOL=NO PROFILE EMS=NO PROFILE CMDKEEP=NO PROFILE TRUNC=NO NNM0357 PROFILE HAS CHANGED NNM0357 PROFILE HAS CHANGED NNM0357 PROFILE HAS CHANGED NNM0357 PROFILE HAS CHANGED NNM0357 PROFILE HAS CHANGED NNM1005 START ZEX0604N PROCESSING COMPLETE.
Procedures and Functions Declaring Procedures and User-Written Functions The following screen shows the results of executing the procedure six times: (14:01) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0605N 4 The square root of 4 is 2 NNM1005 START ZEX0605N PROCESSING COMPLETE. NCLID 002041 START ZEX0605N 9 The square root of 9 is 3 NNM1005 START ZEX0605N PROCESSING COMPLETE.
Procedures and Functions Declaring Procedures and User-Written Functions The following screen shows the results of executing the procedure: (14:12) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0606N SYSPARMS PRELOAD=NNMPROC1 SYSPARMS PRELOAD=NNMPROC2 SYSPARMS PRELOAD=NNMPROC3 NNM0604 SYSPARMS PRELOAD=NNMPROC1 OPERAND ACCEPTED NNM0604 SYSPARMS PRELOAD=NNMPROC2 OPERAND ACCEPTED NNM0604 SYSPARMS PRELOAD=NNMPROC3 OPERAND ACCEPTED NNM1005 START ZEX0606N PROCESSING COMPLETE.
Procedures and Functions Terminating Execution of the Current Procedure or Function Terminating Execution The procedure or function that is executing within an NCL process is the current of the Current procedure or function.
Procedures and Functions Terminating Execution of the Current Procedure or Function The EXIT Statement— Procedures Only The EXIT core statement terminates the execution of a procedure. You cannot use it to terminate the execution of a function. When you exit, you terminate execution of the current procedure. The EXIT statement returns from the current procedure to the procedure or function that called it. The EXIT statement can set a return code in &SYS.RETCODE.
Procedures and Functions Terminating Execution of the Current Procedure or Function The RETURN Statement— Procedures and Functions The RETURN core statement terminates the execution of a procedure or function. Using the RETURN Statement in Procedures Using the RETURN core statement in a procedure is optional. It is used to return a list of variables to the calling procedure or function.
Procedures and Functions Terminating Execution of the Current Procedure or Function The following screen shows the results of executing the procedure: (09:13) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0608N Top level It is a SUNNY day today First level Top level It is a RAINY day today so I need an umbrella NNM1005 START ZEX0608N PROCESSING COMPLETE.
Procedures and Functions Terminating Execution of the Current Procedure or Function placed in the variable &2. Both parameters are passed to the ROOTN function when the function is called. The values are checked by the built-in function, TYPECHK. If both parameters are numbers, the ROOTN function calculates the root of the first parameter using the second parameter. The ROOTN function returns the result (or an error message) using a RETURN statement.
Procedures and Functions Passing Parameters to Procedures and Functions Passing Parameters to A parameter is a value passed to a procedure or function when the procedure or Procedures and function is called. This subsection discusses how to use parameter variables, how to Functions use the system variables &SYS.PARMCNT and &SYS.ALLPARMS, and how to specify parameter handling in a procedure declaration.
Procedures and Functions Passing Parameters to Procedures and Functions The following screen shows the results of executing the procedure: (09:57) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0610N John Smith Top level &1 is John &2 is Smith Value of &SYS.PARMCNT is 2 Value of &SYS.ALLPARMS is John Smith First level &1 is One &2 is Two &3 is Three Value of &SYS.PARMCNT is 3 Value of &SYS.ALLPARMS is John Smith Top level &1 is Gold &2 is Silver &3 is Three Value of &SYS.
Procedures and Functions Passing Parameters to Procedures and Functions Procedure Declarations and Parameters When you declare a procedure (but not a function), you can specify how you want the procedure to treat any parameters that are passed to it when the procedure is called. You can specify how you want NCL to handle the case of alphabetic characters with the [NO]FOLD keyword. In addition, you can specify how you want NCL to parse parameters with the EXTPARSE keyword.
Procedures and Functions Passing Parameters to Procedures and Functions The following screen shows the results of executing the procedure: (11:39) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0611N John Smith &1 is JOHN &2 is SMITH NNM1005 START ZEX0611N PROCESSING COMPLETE.
Procedures and Functions Passing Parameters to Procedures and Functions Parsing Parameters The EXTPARSE keyword specifies how you want a parameter string to be parsed when it is passed to a procedure. EXTPARSE has two values: SIMPLE (for simple parsing) and SMART (for smart parsing). Simple Parsing. With simple parsing, NCL uses blanks to delimit parameters. Quotes (" ") and commas (,) become part of the parameters.
Procedures and Functions Passing Parameters to Procedures and Functions Smart Parsing. With smart parsing, NCL uses blanks and commas (,) to delimit parameters. However, you can use a quoted string to preserve blanks and commas and so pass blanks and commas as part of a parameter. You can double a particular quote to pass a single instance of the quote as part of a parameter.
Procedures and Functions Sharing Variables to Procedures and Functions Sharing Variables to Every procedure and function called during the execution of an NCL process creates Procedures and its own set of variables. These variables are local to the procedure or function and are Functions deleted when the procedure or function terminates. Although the variables in one procedure or function are local to that procedure or function, you can temporarily share them with other procedures or functions.
Procedures and Functions Sharing Variables to Procedures and Functions Caution The following four settings of the CONTROL verb are equivalent; all prohibit variable sharing: CONTROL NOSHRVARS CONTROL NOSHRVARS=NO CONTROL SHRVARS CONTROL SHRVARS=NO Overriding the CONTROL Verb When Calling a Procedure. There are two ways to override the default setting of the CONTROL verb when you call a procedure.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (15:32) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0614N Pre-procedure call var_1 is One Post-procedure call (NOSHRVARS), var_1 is One Post-procedure call (SHRVARS), var_1 is Two NNM1005 START ZEX0614N PROCESSING COMPLETE.
Procedures and Functions Sharing Variables to Procedures and Functions The following example shows the second way in a complete procedure: zex0624n: PROCEDURE /* Sharing with the CALL statement */ /* Default is CONTROL NOSHRVARS */ &var_1 = One SAY "Pre-procedure call var_1 is "&var_1 CALL control_proc SAY "Post-procedure call (NOSHRVARS), var_1 is "&var_1 CALL control_proc SHARE &var_1 SAY "Post-procedure call (CALL SHARE), var_1 is "&var_1 control_proc: PROCEDURE &var_1 = Two END control_proc END zex0624
Procedures and Functions Sharing Variables to Procedures and Functions Overriding the CONTROL Verb When Calling a Function. There is only one way to override the default setting of the CONTROL verb when you call a function—by using the CONTROL verb to specify a share list. You cannot override the default setting of the CONTROL verb on the function declaration of the callee function.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (08:53) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0625N Pre-function call var_1 is One Post-function call (NOSHRVARS), var_1 is One Post-function call (SHRVARS), var_1 is Two NNM1005 START ZEX0625N PROCESSING COMPLETE.
Procedures and Functions Sharing Variables to Procedures and Functions Sharing Through a Procedure or Function Declaration When you declare a procedure, by using the PROCEDURE core statement, or a function, by using the FUNCTION core statement, you can specify whether it can share variables or not by using either the SHARE or NOSHARE keyword.
Procedures and Functions Sharing Variables to Procedures and Functions When the CONTROL_PROC1 procedure is called from the top-level procedure, the default setting of CONTROL NOSHRVARS is in effect: the value of &VAR_1 does not change. When the CONTROL_PROC2 procedure is first called, CONTROL NOSHRVARS is in effect: again, the value of &VAR_1 does not change.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (12:54) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0616N Pre-procedure call var_1 is One Post-procedure call var_1 is One Post-procedure call (SHARE), var_1 is Two NNM1005 START ZEX0616N PROCESSING COMPLETE.
Procedures and Functions Sharing Variables to Procedures and Functions You cannot include the following variables in a share list: &abc&xyz &abc.xyz &abc&(xyz) &glblabc &sys.retcode /* /* /* /* /* Complex variable Compound variable Nested variable Global variable System variable */ */ */ */ */ The following examples specify variables in a share list: CONTROL SHRVARS=&a CONTROL NOSHRVARS=&a CONTROL SHRVARS=(&a,&b*,&c.) CONTROL NOSHRVARS=(&a,&b*,&c.
Procedures and Functions Sharing Variables to Procedures and Functions The following example shows how specifying the NO keyword on a procedure declaration affects variable sharing: zex0617n: PROCEDURE /* The NO keyword in a share list */ &var_1 = One SAY "Pre-procedure call var_1 is "&var_1 CALL control_proc SAY "Post-procedure call var_1 is "&var_1 CALL control_proc SHARE &var_1 SAY "Post-procedure call var_1 is "&var_1 control_proc: PROCEDURE SHARE NO &var_1 = Two END control_proc END zex0617n The follo
Procedures and Functions Sharing Variables to Procedures and Functions Using the CALLER Keyword in a Share List When any procedure or function uses the CALLER keyword in a share list specification, the keyword is logically replaced by the contents of the share list provided by the caller at the time the current procedure or function is called. The CALLER keyword does not preclude the use of other variable specifications in a share list.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (13:25) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0618N Pre-procedure call var_1 is One Post-procedure call var_1 is One Post-procedure call var_1 is Two NNM1005 START ZEX0618N PROCESSING COMPLETE.
Procedures and Functions Sharing Variables to Procedures and Functions Using Two SHARE Keywords If both the caller and callee have specified a list of variables to share using the SHARE keyword, then the intersection of both lists is shared.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (13:41) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0619N Pre-procedure call vars are One 1 First Begin Post-procedure call vars are One 1 First Begin Post-procedure call vars are One 1 Last Begin NNM1005 START ZEX0619N PROCESSING COMPLETE.
Procedures and Functions Sharing Variables to Procedures and Functions Using Two NOSHARE Keywords If both the caller and callee have specified a list of variables that are not to be shared using the NOSHARE keyword, then all variables are shared except those that are the union of both NOSHARE lists.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (13:46) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0620N Pre-procedure call vars are One 1 First Begin Post-procedure call vars are One 1 First Begin Post-procedure call vars are One 1 First End NNM1005 START ZEX0620N PROCESSING COMPLETE.
Procedures and Functions Sharing Variables to Procedures and Functions Using One SHARE Keyword and One NOSHARE Keyword If either the caller or callee has specified the NOSHARE keyword and the other has specified the SHARE keyword, the variables shared consist of those specified by the SHARE keyword less those specified by the NOSHARE keyword.
Procedures and Functions Sharing Variables to Procedures and Functions The following screen shows the results of executing the procedure: (13:51) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0621N Pre-procedure call vars are One 1 First Begin Post-procedure call vars are One 1 First Begin Post-procedure call vars are Two 2 First Begin NNM1005 START ZEX0621N PROCESSING COMPLETE.
Procedures and Functions Calling Procedures and Functions Calling Procedures This subsection explains how to call a procedure or function. It describes procedure and Functions and function call syntax. It discusses how the syntax of the call affects how NCL searches for a procedure or function. Finally, it describes how NCL searches for the labels of internal procedures and functions.
Procedures and Functions Calling Procedures and Functions The following example simulates a race between person A and person B to illustrate procedure calling: zex0622n: PROCEDURE /* Race between person A and person B &a = 0 /* A starts from zero &b = 1 /* B gets a headstart CALL progress SHARE &a,&b /* Check headstart DO 7 /* Begin race &a = &a + RANDOM(1,6) /* A starts first CALL progress SHARE &a,&b /* Who's ahead now? &b = &b + RANDOM(1,6) /* B's turn CALL progress SHARE &a,&b /* Who's ahead now? END /
Procedures and Functions Calling Procedures and Functions Calling a Function You can call a function only from within an expression. A call to a function can occur whenever a value is required in an expression. The following example shows how a function call returns a single result that is used to evaluate an expression: zex0623n: PROCEDURE /* Calling a function */ SAY "The mean is "mean(&SYS.
Procedures and Functions Calling Procedures and Functions Procedure and Function Name Syntax and Search Order You can specify the name of the procedure or function you want to call in three different ways. The way in which you identify a procedure or function determines the order in which NCL searches for it.
Procedures and Functions Calling Procedures and Functions Function Name Syntax and Search Order The following table summarizes how the syntax of a function name affects how NCL searches for it; the table shows that the search order is affected by the use of quotes (“ ”) and parentheses (( )) around the function name: Function Name Syntax Comment Search Order function-name(…) The function name must be a valid symbol. "function-name"(…) With quotes.
Procedures and Functions Calling Procedures and Functions Searching for Procedure and Function Labels Searching for and finding the label of an internal procedure or function is governed by rules that define search order and the labels that NCL can see from any point. From any point within a procedure or function, that procedure or function sees labels in the following order: 1. The label(s) of all direct children. 2. Its own label(s) and the labels of its peers. 3.
7 Run-Time Error Handling This section discusses how to handle errors detected during the execution of an NCL process. These are called run-time errors.
Run-Time Error Handling Run-Time Errors and Error Messages It is impossible to describe how to handle all types of errors because error handling depends on both the specific error and the purpose of the NCL procedure in which the error occurs. Accordingly, this section provides you with general guidelines rather than an analysis of specific situations. Run-Time Errors and Error Messages There are many types of run-time errors.
Run-Time Error Handling Handling Run-Time Errors The following screen shows the results of attempting to execute the procedure three times: (13:47) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0701N 10 A NNM1004 NCLID 002032: ZEX0701N 3 ERROR TYPE_ERROR CODE 4 START ZEX0701N 10 0 NNM1004 NCLID 002033: ZEX0701N 3 ERROR ARITH_ERROR CODE 10 START ZEX0701N 10 2 10 divided by 2 is 5 NNM1005 START ZEX0701N PROCESSING COMPLETE.
Run-Time Error Handling Writing an Error Handler Writing an Error Handler If you want to trap errors during the execution of an NCL process, you must write an error handler before executing the NCL procedure. There are three parts to writing an error handler: Specifying the error condition to trap Writing the statement to process the error Recovering from the error (if possible) Specifying the Error Condition to Trap The ON core statement declares a routine to handle an error condition.
Run-Time Error Handling Writing an Error Handler System-Defined Error Handlers for Specific Conditions There are various system-defined error handlers for specific conditions.
Run-Time Error Handling Writing an Error Handler Note Writing the Statement to Process the Error The order in which multiple error handlers are declared is not significant to NCL when they are executed one after the other in a block of statements. Once NCL has trapped an error, it processes the error according to the statement following the specified condition.
Run-Time Error Handling Writing an Error Handler Specifying a Single Action After an Error To direct NCL to perform a single action, use a single statement following the keyword that specifies the error condition. The following example directs NCL to execute the FLUSH core statement when it detects an error: zex0703n: PROCEDURE /* Specifying a single action */ ON ERROR FLUSH SAY &1" divided by "&2" is "&1/&2 SAY Normal termination END zex0703n This explicitly terminates execution of the NCL process.
Run-Time Error Handling Writing an Error Handler The following example directs NCL to display a series of messages using &SYS.ERROR system variables when it detects an error, and to exit the procedure using the EXIT core statement: zex0704n: PROCEDURE /* Specifying more than one action */ ON ERROR DO SAY "Condition is "&SYS.ERROR.COND SAY "Code is "&SYS.ERROR.CODE SAY "Line is "&SYS.ERROR.LINE SAY "Column is "&SYS.ERROR.COLUMN SAY "Error text is "&SYS.ERROR.TEXT SAY "Statement is "&SYS.ERROR.
Run-Time Error Handling Writing an Error Handler Specifying Alternative Actions Using Different Error Handlers When you use more than one error handler, you can use each to direct NCL to perform different actions.
Run-Time Error Handling Writing an Error Handler The following screen shows the results of attempting to execute the procedure twice: (14:04) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0705N 9999999999999999999999 9999999999999999999999999999999999 Arithmetic error Condition is ARITH_ERROR Code is 3 Procedure library is $DATA2.ZNCLPGN Proc/Func is ZEX0705N NNM1005 START ZEX0705N PROCESSING COMPLETE.
Run-Time Error Handling Writing an Error Handler Recovering From the Error If you do not specify how to recover from an error or explicitly use the FLUSH core statement, NCL terminates execution of the NCL process. After you detect an error, however, you may want to attempt to recover from the error and continue execution. There are two core statements that allow you to attempt to recover from an error: RESUME and RETRY.
Run-Time Error Handling Writing an Error Handler The following screen shows the results of executing the procedure: (14:11) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0706N Divide 100 by what number? Please enter ZZZZZ or a number |NM1060 PROCEDURE ZEX0706N NCLID 2049 PAUSED GO ID=2049 17 100 divided by 17 is 5.
Run-Time Error Handling Writing an Error Handler If you enter an invalid denominator, an error handler displays an error message, substitutes the valid denominator of 1, and retries the statement raising the error. The line that can raise the ON condition, and the line that is retried, in this example is the following: SAY "100 divided by "&1" is "100/&1 Entering ZZZZZ rather than a number terminates execution of the NCL process normally.
Run-Time Error Handling Setting an Error Handler Setting an Error After you have written an error handler, the NCL process must then set it by running Handler through the code containing the ON statement(s) without any errors occurring. The simplest way to do this is execute all ON statements as soon as the NCL procedure begins execution.
Run-Time Error Handling Raising an Error Handler Raising an Error Handler Once the error handler is set, the error condition for which it is set can be raised in two ways: automatically by NCL or explicitly by using the SIGNAL core statement. Using NCL to Raise an Error Handler Automatically NCL can raise an error handler at any time during the course of NCL process execution when it detects an error. The following steps summarize the action that NCL takes: 1.
Run-Time Error Handling Scope and Error Handling Scope and Error Error handlers are associated with blocks of core statements. Blocks are established by Handling the DO, FUNCTION, PROCEDURE, and SELECT core statements. The scope of an error handler is determined by the boundaries of a block. Any block, including nested blocks to any nesting level, can set up its own routines to handle errors occurring within the block.
Run-Time Error Handling Scope and Error Handling Scope and Replacing an Error Handler If they are in the same block, you can replace an existing error handler with another error handler that handles the same condition by running through the code of the new error handler.
Run-Time Error Handling Scope and Error Handling Scope and Searching for an Error Handler Scope affects how NCL searches for an error handler from any point. When NCL searches for an error handler, it does so in the following way: 1. It looks for a specific error handler within its current block. 2. If it cannot find one, it progressively looks for one, in nested order, in all outer blocks. The last block it searches is the block at the open code level of the current procedure or function. 3.
Run-Time Error Handling Scope and Error Handling Figure 7-1. Search Order for an Error Handler PROC1: PROCEDURE 6 ON ERROR ... 5 FUNC1: FUNCTION PROC2: PROCEDURE 4 PROC3: PROCEDURE 3 2 PROC4: PROCEDURE PROC5: PROCEDURE 1 Error raised here 003 Scope and Recovering From an Error An error may be raised in one NCL procedure or function, even though the error handler that handles the error may be located in a different NCL procedure or function.
Run-Time Error Handling Scope and Error Handling This affects how certain core statements operate when they are executed within the error handler. It is recommended that you use the RETRY or RESUME core statement to recover from an error. These statements transfer control from the error handler that is handling the error back to the procedure or function where the error was raised.
Run-Time Error Handling System Variables Containing Error Information System Variables NCL provides system variables that you can use to obtain information when a runContaining Error time error occurs during the execution of an NCL process. These variables are listed in Information Table 7-2. These variables have the following characteristics: They begin with the stem and substem, &SYS.ERROR. They are read-only variables. They are accessible only from within an error handler.
Run-Time Error Handling Using the &SYSMSG Variable Using the &SYSMSG When a run-time error is raised, the &SYSMSG variable may contain textual Variable information to help you determine the cause of the error. Unlike most system variables, that is, variables beginning with the reserved stem of SYS., you can modify the contents of the &SYSMSG variable. Verbs that can set &SYSMSG include the CNMREAD and CNMSEND verbs, some FILE verbs, the PANEL verb, some PSEND verbs, some SECCALL verbs, and the START verb.
Run-Time Error Handling System-Defined Error Handlers for Specific Conditions System-Defined Error This subsection lists and then describes the system-defined error handlers that are Handlers for Specific available to trap specific conditions, including the system variables that are set Conditions specifically when the error handler is raised. Table 7-3 lists the available error handlers. Table 7-3.
Run-Time Error Handling System-Defined Error Handlers for Specific Conditions The ARITH_ERROR Error Handler If present, the ARITH_ERROR error handler traps overflow, underflow, and divisionby-zero errors that occur when performing arithmetic operations. This error handler is set by the following ON statement: ON ARITH_ERROR statement The following system variables are set specifically for this error handler: System Variable Setting of System Variable &SYS.ERROR.VALUE &SYS.ERROR.VALUEOK &SYS.ERROR.
Run-Time Error Handling System-Defined Error Handlers for Specific Conditions The following system variables are set specifically for this error handler: System Variable Setting of System Variable &SYS.ERROR.VALUE &SYS.ERROR.VALUEOK Contains the text of the target label. Contains 1 (TRUE) or 0 (FALSE). See Section 4, “Initial NCL Procedure Development,” for more information on labels.
Run-Time Error Handling System-Defined Error Handlers for Specific Conditions See Section 14, “Working With Panels,” for more information on using panels and the END function key. The PANEL_ERROR Error Handler If present, the PANEL_ERROR error handler is invoked as a consequence of panel validation processing by Panel Services, for example, attempting to display a panel that does not exist.
Run-Time Error Handling System-Defined Error Handlers for Specific Conditions The PSEND_ERROR Error Handler If present, the PSEND_ERROR error handler traps errors resulting from the use of the PSEND verbs. From the PSEND OPEN verb, errors include being unable to access the specified server class.
Run-Time Error Handling System-Defined Error Handlers for Specific Conditions The following system variables are set specifically for this error handler: System Variable Setting of System Variable &SYS.ERROR.NAME Contains the name after all substitution operations have been performed. Contains the value that had a conversion attempted upon it. Contains 1 (TRUE) or 0 (FALSE). &SYS.ERROR.VALUE &SYS.ERROR.
8 Executing NCL Procedures An NCL procedure that is executing is called an NCL process. This section discusses the following topics: Execution techniques Using timer commands to execute NCL procedures Using virtual users to execute NCL procedures Factors affecting NCL procedure location Displaying information about NCL processes Controlling NCL process execution Note An NCL process executes within a NonStop NET/MASTER MS Guardian process and must be executed from NonStop NET/MASTER MS.
Executing NCL Procedures Execution Techniques You can enter the START command from any command input line including the OCS command input line and the Log Browse command input line. From the OCS command input line, the general form of the START command is: START ncl-procedure-name From the Log Browse command input line, the general form of the START command is: /START ncl-procedure-name Any NCL procedure can execute the START command using the CMD core statement or the INTCMD verb.
Executing NCL Procedures Execution Techniques You can enter the EXEC command from any command input line including the OCS command input line and the Log Browse command input line. From the OCS command input line, the general form of the EXEC command is: EXEC ncl-procedure-name From the Log Browse command input line, the general form of the EXEC command is: /EXEC ncl-procedure-name Any NCL procedure can execute the EXEC command using either the CMD core statement or the INTCMD verb.
Executing NCL Procedures Execution Techniques Implicit Execution Implicit NCL procedure execution refers to execution without using the NonStop NET/MASTER MS START or EXEC command. Examples of NCL procedures that are implicitly executed are: MSGPROC NCL procedures NCL procedures that replace NonStop NET/MASTER MS commands Unrecognized commands MSGPROC NCL Procedures MSGPROC NCL procedures process messages flowing to an OCS window.
Executing NCL Procedures Execution Techniques An example of a command you may want to replace with an NCL procedure is the LIST command. You may want to write an NCL procedure that strips the message numbers from the beginning of each line of an NCL procedure as the line is displayed.
Executing NCL Procedures Using Timer Commands to Execute NCL Procedures The screen lists the ZEX0801N NCL procedure using the LIST command from the NonStop NET/MASTER MS command table, replaces the LIST command with the LIST NCL procedure by using the SYSPARMS CMDREPL command, lists the NCL procedure again using the preloaded NCL procedure, and unloads the preloaded NCL procedure by using the SYSPARMS UNLOAD command.
Executing NCL Procedures Using Virtual Users to Execute NCL Procedures The following screen shows the results of the EVERY command, how you use the SHOW TIMER command to display timer commands in the timer queue, and the results of executing the START LINKSCAN command once: (15:37) --------------------- OPERATOR CONTROL SERVICES --------------------EVERY :10 KEEP=MON TID=SCAN CMD=START LINKSCAN NNM1706 COMMAND ACCEPTED, PURGE ID NUMBER IS 5 SHOW TIMER NNM1721 ID BY INTERVAL -USERID-R LIM CNT K/P ENV P/M TI
Executing NCL Procedures Factors Affecting NCL Procedure Location The following example sends a command to the Background Monitor to execute at a certain time. This timer command tells the Background Monitor to execute the NCL procedure NETMON at 18:00. AT 18:00 ROUTE=MON CMD=START NETMON Once you have submitted a command to a virtual user, its processing is managed entirely by the virtual user. Processing is not affected if you exit OCS or log off from your NonStop NET/MASTER MS system.
Executing NCL Procedures Factors Affecting NCL Procedure Location keeps all NCL procedures that are currently executed by one or more NCL processes if the value of the SYSPARMS NCLPRSHR command is either YES or a number. (NCL procedures that are preloaded using SYSPARMS PRELOAD are displayed with a status of PRELOAD by the SHOW PRELOAD command.) If the value of the SYSPARMS NCLPRSHR command is a number, your NonStop NET/MASTER MS system also maintains a list called the retain list.
Executing NCL Procedures Factors Affecting NCL Procedure Location Note Logically, there is only one active, retain, and pend-unload list. In practice, all NonStop NET/MASTER MS Guardian processes that support NCL support one of each type of list. The number of lists, therefore, depends on the way you have configured the operating mode of your NonStop NET/MASTER MS system—basic, extended basic, or advanced. Refer to the NonStop NET/MASTER MS System Management Guide for more information on operating modes.
Executing NCL Procedures Factors Affecting NCL Procedure Location if still unsuccessful, NonStop NET/MASTER MS searches the distributed NCL object file. Your NonStop NET/MASTER MS system assumes that the first match it finds in the search path is the NCL procedure to execute.
Executing NCL Procedures Factors Affecting NCL Procedure Location 4. NCL object file, $DATA.ZNNMNDO.NCLOBJ1 5. NCL object file, $DATA.ZNNMNDO.NCLOBJ2 By specifying the files in a different order, you can change the order of searching files for NCL procedures. The additional files are searched in the order specified following the search of the distribution procedure library. Refer to the NonStop NET/MASTER MS System Management Guide for more information on customizing the NCL procedure search path.
Executing NCL Procedures Factors Affecting NCL Procedure Location Unloading You can use the SYSPARMS UNLOAD command to unload an NCL procedure. If the NCL process is being executed, a warning message is sent to the issuer of the command. The NCL process continues to execute but can no longer be used by other users. When it is no longer in use, it is deleted from memory.
Executing NCL Procedures Factors Affecting NCL Procedure Location When Sharing Is Active If you specify SYSPARMS NCLPRSHR=YES, then NCL procedures that are loaded for execution can be shared. This means that, if you are executing an NCL procedure, any other user that wants to execute it will use the same copy. The shared NCL procedure is kept in the active list while it is being executed. While it is in the active list, any other user can execute it.
Executing NCL Procedures Factors Affecting NCL Procedure Location If test mode is off, the NCL process that executes may not be the most recent version. The following command sets test mode off: PROFILE NCLTEST=NO Hint To improve the performance of an NCL process, set test mode on only when developing and testing NCL procedures.
Executing NCL Procedures The NCL Process Identifier (NCL ID) If NonStop NET/MASTER MS cannot find the NCL procedure using the active and the retain lists, it tries to load the NCL procedure from disk. It uses the default or customized search path to search, beginning from the user procedure library. If NonStop NET/MASTER MS finds the NCL procedure, it automatically compiles and executes it.
Executing NCL Procedures Displaying Information About NCL Processes Displaying Information Table 8-1 lists the NonStop NET/MASTER MS commands you can use to display About NCL Processes information about NCL processes. This subsection discusses the SHOW NCL, SHOW NCLSTAT, and SHOW PRELOAD commands. The SHOW PAUSE command is described later in this section and in Section 13, “Interaction With Users and Terminals.” The SHOW LOCKS command is described in Section 18, “Advanced NCL Programming.” Table 8-1.
Executing NCL Procedures Displaying Information About NCL Processes NCL processes executing a specific NCL procedure by using the following command: SHOW NCL PROC=ncl-procedure The following example displays information about all active NCL processes: SHOW NCL=ALL The following screen shows the results of executing the command: (14:28) ---------------------------------------------------------------------SHOW NCL=ALL NNM1036 NCLID BASEPROC CURRENT LEV W TYPE INIT OWNER G P P-UNITS NNM1037 1 ZHWKMMNN ZHWKMMN
Executing NCL Procedures Controlling NCL Process Execution The following screen shows the results of executing the command: (10:56) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW PRELOAD NNM1050 NAME STATUS USERS REFCNT STMTS NCLBUF LIBRARY AGEUSE NNM1051 INITCMD RETAINED 0 1 13 2 ZNCLPGN 1 NNM1051 LIST CMDREPL 0 0 14 2 ZNNMNCS NNM1051 OPSYS CMDREPL 0 0 173 10 ZNNMNCS NNM1051 PROGRUN CMDREPL 0 0 50 10 ZNNMNCS NNM1051 ZCENFACN PRELOAD 0 0 1468 60 ZNNMNCS NNM1051 ZEDSMNUN PRELOAD 0
Executing NCL Procedures Controlling NCL Process Execution The FLUSH Command You can use the FLUSH command from either the OCS command input line or an NCL process to terminate an NCL process. The FLUSH command does not just terminate the NCL procedure which happens to be executing at the time—FLUSH terminates the NCL process and any of its dependent NCL processes. (Dependent NCL processes are discussed in Section 16, “Environments and Command Processing.
Executing NCL Procedures Controlling NCL Process Execution To use the GO command to restart a specific NCL process follow these steps: 1. Use the SHOW PAUSE command to display information about the NCL processes that are currently paused, for example: SHOW PAUSE=ALL 2. Examine the screen display to determine the NCL ID of the NCL process you want to restart. 3.
Executing NCL Procedures Controlling NCL Process Execution (This page left intentionally blank) 8–22 106160 Tandem Computers Incorporated
9 Debugging an NCL Process This section discusses how to debug an NCL process by using the NonStop NET/MASTER Management Services (MS) DEBUG commands. These commands assist you in detecting errors in logic and typography that prevent an NCL process from executing correctly. DEBUG commands allow you to suspend execution of an NCL process at any point and obtain a summary of information about it.
Debugging an NCL Process Why Use the DEBUG Commands? For the complete syntax of NonStop NET/MASTER MS commands, refer to the NonStop NET/MASTER MS Command Reference Manual.
Debugging an NCL Process Why Use the DEBUG Commands? 4. Repeat steps 1 through 3 if an error still exists. When you are familiar with the DEBUG commands, you will find that they can save you considerable development time. Note You can also enter DEBUG commands from an NCL process, by using either the CMD core statement or the INTCMD verb. Entering NonStop NET/MASTER MS commands from an NCL process is discussed in Section 16, “Environments and Command Processing.
Debugging an NCL Process Why Use the DEBUG Commands? Displaying Decompiled Source Code When debugging, it is good practice to proofread the source code for bugs. Without the DEBUG commands, you can examine only the original source code, either by using the LIST command (which displays the source code in your OCS window) or by using Edit Services. However, examining the original source code is not always effective in detecting bugs.
Debugging an NCL Process Why Use the DEBUG Commands? Multiple statements in a certain direction Multiple statements at a certain nesting level Using Breakpoints to Suspend Execution A breakpoint is a position in an NCL process at which NCL suspends execution. You typically set a breakpoint in the source code where you think a bug is located, by using the DEBUG BREAKPOINT command. You can place a breakpoint at the following positions in an NCL process: At the first statement of an error handler.
Debugging an NCL Process Why Use the DEBUG Commands? You can also dynamically modify the value of a variable, by using the DEBUG MODIFY command. You could use this command, for example, to modify the value of the control variable in a DO loop, to alter the logic of an NCL process; the values of variables passed to a procedure or function, to see the result of sharing certain variables; the value of an arithmetic term in an expression, to obtain a different result; and so on.
Debugging an NCL Process Debugging Guidelines Loading an External Procedure Before Execution If you are debugging an NCL process that calls an external NCL procedure, you can use the DEBUG LOAD command to load the file containing the external procedure before the NCL process requires it. This allows you to set breakpoints in the external procedure before it is executed—for example, at the entry to the NCL procedure—and can help you isolate the bug(s) you are looking for.
Debugging an NCL Process Debugging Guidelines If you obtain incorrect output, proofread the source code, looking for typographical and logical errors. If you cannot find the bug(s) causing the run-time error or the incorrect output, consider debugging the NCL process. 4. When Debugging an NCL Process Note 9–8 Consider defining local equate commands and function keys that abbreviate DEBUG commands, as described later in this section. When debugging an NCL process: 1.
Debugging an NCL Process Debugging Guidelines 8. When execution is suspended at the first, or any breakpoint, the tasks you would normally perform are the following: Display the current statement and, if necessary, surrounding statements by using the DEBUG SOURCE command. Examine the values of relevant variables by using the DEBUG DISPLAY command and, if necessary, modify the values of variables by using the DEBUG MODIFY command.
Debugging an NCL Process Debugging Guidelines Defining the Default NCL ID The default NCL ID is defined as that of the most current NCL process being debugged. When you use DEBUG START for an environment, the default NCL ID is set only if the existing debug NCL ID is null, or the process that was being debugged has terminated.
Debugging an NCL Process Defining Debug Equates and Function Keys Defining Debug Equates and Function Keys DEBUG commands can exceed the length of the OCS command input line, especially if the screen is vertically split into two OCS windows. For this reason and to reduce typing, you may find it convenient to define local equate commands and function keys that abbreviate lengthy DEBUG commands before starting your debug session.
Debugging an NCL Process Defining Debug Equates and Function Keys The following screen shows the results of executing the procedure: (06:44) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0901N NNM0235 TEXT SET FOR EQUATE STRING RES NNM0235 TEXT SET FOR EQUATE STRING TRC NNM0235 TEXT SET FOR EQUATE STRING DISP NNM0235 TEXT SET FOR EQUATE STRING MOD NNM0235 TEXT SET FOR EQUATE STRING HOLD NNM0235 TEXT SET FOR EQUATE STRING LOAD NNM0235 TEXT SET FOR EQUATE STRING BP NNM0235 TEX
Debugging an NCL Process Examples Used to Illustrate DEBUG Commands Examples Used to The discussion of individual DEBUG commands throughout the rest of this section Illustrate DEBUG uses two NCL procedures to illustrate the debugging tasks you can perform with each Commands command. These are the ZEX0902N NCL procedure and the ZEX0903N NCL procedure. Purpose of the ZEX0902N NCL Procedure The purpose of the ZEX0902N NCL procedure is to analyze a string of characters.
Debugging an NCL Process Examples Used to Illustrate DEBUG Commands EXIT /**************************** TOP_TITLE *****************************/ /* The top_title function returns the top and bottom lines of the */ /* histogram. The line shows the number of words having a certain */ /* number of characters. The line looks like this: */ /* ---| 1 | 2 | */ /* and so on to the value of MAX_WORDS.
Debugging an NCL Process Examples Used to Illustrate DEBUG Commands Output of the ZEX0902N NCL Process The following screen shows the results of executing the procedure from the OCS command input line using the START command: START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG (11:22) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG |NM1060 PROCEDURE ZEX0902N NCLID 1028 PAUSED GO ID=1028 Y ---| 1 | 2 | 3 | 4 | 5 | 6 | 7
Debugging an NCL Process Examples Used to Illustrate DEBUG Commands Three words that are five characters in length: QUICK, BROWN, and JUMPS (shown by bar 3). Purpose of the ZEX0903N NCL Procedure The purpose of the ZEX0903N NCL procedure is to simply pause execution. This NCL procedure is used in conjunction with the ZEX0902N NCL procedure when discussing how to use the DEBUG START command to target various types of NCL processes for debugging.
Debugging an NCL Process Starting a Single Debug Session Starting a Single To start a single debug session, you must use the DEBUG START command. You Debug Session must execute the DEBUG START command before you can use any other DEBUG command. When starting a debug session, you can target: A single NCL process in any environment. One or more NCL processes by execution state: currently executing, newly executed, or both types.
Debugging an NCL Process Starting a Single Debug Session The following screen shows how to target a single NCL process in OCS, by entering commands from the OCS command input line: (12:47) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1051 PAUSED SHOW NCL NNM1036 NCLID BASEPROC CURRENT LEV W TYPE INIT OWNER G P P-UNITS NNM1037 1051 ZEX0902N ZEX0902N 1 1 START NMTJN NMTJN 1 1 21 NNM1041 ....
Debugging an NCL Process Starting a Single Debug Session Targeting Currently Executing NCL Processes To target currently executing NCL processes in the current execution environment when you start a debug session, follow these steps: 1. Execute one or more NCL procedures. 2. Use the DEBUG START PROCS=CURRPROCS command to start the debug session. Each currently executing NCL process in the environment is suspended at the statement it is currently executing. 3.
Debugging an NCL Process Starting a Single Debug Session assigned the default NCL ID. You can subsequently use other DEBUG commands to continue debugging the ZEX0902N NCL process, or you can change the current NCL ID by using the DEBUG SET ID=ncl-id command. Targeting Newly Executed NCL Processes To target newly executed NCL processes in the current execution environment when you start a debug session, follow these steps: 1.
Debugging an NCL Process Starting a Single Debug Session Targeting Both Currently Executing and Newly Executed NCL Processes To target both currently executing and newly executed NCL processes in an environment when you start a debug session, follow these steps: 1. Execute one or more NCL procedures. 2. Use the DEBUG START PROCS=ALLPROCS command to start the debug session. Each currently executing NCL process in the environment is suspended at the statement it is currently executing. 3.
Debugging an NCL Process Starting a Single Debug Session NCL processes. The DEBUG SOURCE command then displays the decompiled source of the suspended line in ZEX0902N, which is the current NCL process. You can subsequently use other DEBUG commands to continue debugging the ZEX0902N NCL process, or you can change the current NCL ID by using the DEBUG SET ID=ncl-id command.
Debugging an NCL Process Starting a Single Debug Session The Results of Targeting a Window The following scenarios illustrate the results of targeting a window by using the WINDOW operand of the DEBUG START command in more detail. It does so from the perspective of an OCS screen in window 1. Targeting Neither Window From OCS Window 1.
Debugging an NCL Process Starting a Single Debug Session Targeting a Window That Is Not Open. If you attempt to target for debugging a window that is not open, the attempt fails. For example, from an OCS screen in window 1, if you target window 2 and window 2 is not open, window 2 is not targeted for debugging.
Debugging an NCL Process Starting a Single Debug Session Targeting the OCS Screen in Window 2 From OCS Window 1. From an OCS screen in window 1, if you target window 2 and window 2 is currently displaying an OCS screen, the primary processing environment associated with the OCS screen is targeted for debugging. You can target currently executing, newly executed, or both types of NCL processes in the environment.
Debugging an NCL Process Starting a Single Debug Session To arrive at the screen in this example, commands and operations were performed in the following sequence: Note 1. OCS was selected from the NonStop NET/MASTER MS primary menu in window 1. 2. The OCSID ONE command was executed from the OCS command input line to identify OCS window 1. 3. The F2 function key was pressed, and the screen was horizontally split in the middle. 4.
Debugging an NCL Process Starting a Single Debug Session Note The USER and TERM operands of the DEBUG START command each have a default authority level of 2. You must have an authority level of at least 2 to target a single NCL process for debugging if you do not own the NCL process. If a user is logged on more than once, it is advisable to specify both the USER and TERM operands to uniquely identify the user.
Debugging an NCL Process Starting a Single Debug Session ZEX0902N NCL process as the current NCL process and use other DEBUG commands to debug the ZEX0902N NCL process. Targeting a Background Processing Environment You can target NCL processes executing in a background processing environment for debugging by specifying the user ID of the virtual user that owns the environment. To do so, follow these steps: 1.
Debugging an NCL Process Starting a Single Debug Session 5.
Debugging an NCL Process Starting Multiple Debug Sessions environment. The DEBUG STEP command shows that the default NCL ID is correctly set to that of the current NCL process, ZEX0903N. Targeting a Dependent Processing Environment This section has discussed debugging in top-level environments, current execution environments, primary processing environments, and background processing environments. You can also target NCL processes in a dependent processing environment.
Debugging an NCL Process Starting Multiple Debug Sessions To start multiple debugging sessions, follow these steps: 1. Execute one or more NCL procedures to debug a specific NCL process or currently executing NCL processes in a debug session. 2. Use the DEBUG START command, with the appropriate operands, to start a single debug session. Then, repeat the DEBUG START command, with the appropriate operands, to start other debug sessions. 3.
Debugging an NCL Process Setting the Current NCL Process Setting the Current When starting a debug session using the DEBUG START command, NonStop NCL Process NET/MASTER MS assigns a default NCL ID to the most current NCL process. You can, however, explicitly set the current NCL process in two ways: by using the DEBUG SET command, or by using the ID operand on any other DEBUG command. After being set, DEBUG commands that do not explicitly use the ID operand refer to the current NCL process.
Debugging an NCL Process Displaying Decompiled Source Code Displaying Decompiled The DEBUG SOURCE command displays decompiled source code. Comments are not Source Code displayed (they are not compiled and, therefore, not decompiled). A statement that spans multiple lines in the source code is shown as a single statement. Multiple statements on a single line in the source code are shown as multiple statements.
Debugging an NCL Process Displaying Decompiled Source Code Displaying the Statement at Which Execution Is Currently Suspended To display the current statement, use the DEBUG SOURCE command with no operands, as the following screen shows: (14:45) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1066 PAUSED DEBUG START ID=1066 NNM1901 NCL 001066 DEBUG SESSION INITIATED NNM1902 NCL 001066 SUSPENDED
Debugging an NCL Process Displaying Decompiled Source Code Displaying a Single Statement at the Current Nesting Level To display a single statement at the current nesting level, use the LOC operand of the DEBUG SOURCE command, followed by a statement number, as the following screen shows: (14:50) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1073 PAUSED DEBUG START ID=1073 NNM1901 NCL 001073 D
Debugging an NCL Process Displaying Decompiled Source Code Displaying a Single Statement at the Specified Nesting Level To display a single statement at the specified nesting level, use the LOC operand of the DEBUG SOURCE command, followed by a statement specification that provides the names of all intermediate procedures and functions, as the following screen shows: (14:57) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM10
Debugging an NCL Process Displaying Decompiled Source Code Displaying Multiple Statements When displaying multiple statements, you can display: All statements, including statements at all lower nesting levels Multiple statements in a certain direction Multiple statements at a certain nesting level Displaying All Statements To display all statements, use both the NESTED=YES and LOC operands of the DEBUG SOURCE command, as the following screen shows: (15:05) --------------------- OPERATOR CONTROL SERVICES -
Debugging an NCL Process Displaying Decompiled Source Code The complete listing of the decompiled source code for the ZEX0902N NCL process is shown next: NNM1926 NCL 000211 NNM1934 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000211 NNM1927 NCL 000
Debugging an NCL Process Displaying Decompiled Source Code Displaying Multiple Statements in a Certain Direction When displaying multiple statements in a certain direction, you can display: Multiple statements in a forward direction from the current statement. Multiple statements in a forward direction from the specified statement. Multiple statements in a backward direction from the current statement. Multiple statements in a backward direction from the specified statement.
Debugging an NCL Process Displaying Decompiled Source Code The following screen displays multiple statements in a forward direction from the specified statement: (15:27) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1102 PAUSED DEBUG START ID=1102 NNM1901 NCL 001102 DEBUG SESSION INITIATED NNM1902 NCL 001102 SUSPENDED AT ZEX0902N.8 LINE 22 GO ID=1102 Y DEBUG SOURCE LOC=ZEX0902N.
Debugging an NCL Process Displaying Decompiled Source Code The following screen displays multiple statements in a backward direction from the current statement: (15:23) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1098 PAUSED DEBUG START ID=1098 NNM1901 NCL 001098 DEBUG SESSION INITIATED NNM1902 NCL 001098 SUSPENDED AT ZEX0902N.
Debugging an NCL Process Displaying Decompiled Source Code The following screen displays multiple statements in a backward direction from the specified statement: (15:32) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1108 PAUSED DEBUG START ID=1108 NNM1901 NCL 001108 DEBUG SESSION INITIATED NNM1902 NCL 001108 SUSPENDED AT ZEX0902N.8 LINE 22 GO ID=1108 Y DEBUG SOURCE LOC=ZEX0902N.
Debugging an NCL Process Displaying Decompiled Source Code Multiple Statements at a Certain Nesting Level The following screen displays multiple statements at a certain nesting level: (15:40) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 1116 PAUSED DEBUG START ID=1116 NNM1901 NCL 001116 DEBUG SESSION INITIATED NNM1902 NCL 001116 SUSPENDED AT ZEX0902N.
Debugging an NCL Process Using Breakpoints to Suspend Execution Using Breakpoints to A breakpoint is a position in an NCL process at which NCL suspends execution. You Suspend Execution typically set a breakpoint in the source code where you think a bug is located, by using the DEBUG BREAKPOINT command. When working with breakpoints, you can: Set breakpoints in an NCL process, by using the DEBUG BREAKPOINT command. List breakpoints in an NCL process, by using the DEBUG LIST BREAKPOINTS command.
Debugging an NCL Process Using Breakpoints to Suspend Execution The following screen sets five breakpoints: (08:36) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0902N THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG NNM1060 PROCEDURE ZEX0902N NCLID 579 PAUSED DEBUG START ID=579 NNM1901 NCL 000579 DEBUG SESSION INITIATED NNM1902 NCL 000579 SUSPENDED AT ZEX0902N.8 LINE 22 GO ID=579 Y DEB B S=16 S=ZEX0902N.LEFT_TITLE.
Debugging an NCL Process Using Breakpoints to Suspend Execution Listing Breakpoints The DEBUG LIST BREAKPOINTS command lists all breakpoints in an NCL process.
Debugging an NCL Process Using Breakpoints to Suspend Execution Clearing Breakpoints The DEBUG CLEAR BREAKPOINT command clears single or multiple breakpoints in an NCL process.
Debugging an NCL Process Displaying and Modifying Variables Displaying and Modifying Variables Note When execution of an NCL process is suspended, you can display and modify the values of variables, using the DEBUG DISPLAY and DEBUG MODIFY commands. When displaying or modifying a variable, you must omit the leading ampersand (&) from the variable name.
Debugging an NCL Process Displaying and Modifying Variables Displaying Variables You can display the values of variables in either normal or hexadecimal format. The display differs according to the format.
Debugging an NCL Process Displaying and Modifying Variables Displaying Variables in Hexadecimal Format After suspending execution at the termination point of the ZEX0902N NCL process, the following screen displays the value of all variables in hexadecimal format: (10:06) --------------------- OPERATOR CONTROL SERVICES ---------------------DEBUG DISPLAY V=* FORMAT=BINARY NNM1922 NCL 000006 ATTR NONE VBL 1 NNM1923 NCL 000006 VAL "544845"X NNM1922 NCL 000006 ATTR NONE VBL 2 NNM1923 NCL 000006 VAL "515549434B"
Debugging an NCL Process Displaying and Modifying Variables Modifying Variables After suspending execution at the termination point of the ZEX0902N NCL process, the following screen displays the value of &2 (QUICK), modifies the value of &2 (to SLOW), and displays the value of all variables in normal format: (10:07) --------------------- OPERATOR CONTROL SERVICES ---------------------DEBUG DISPLAY V=2 NNM1921 NCL 000006 VBL 2 VAL "QUICK" DEBUG MODIFY V=2 VAL=SLOW NNM1932 NCL 000006 VBL 2 UPDATED DEBUG DIS
Debugging an NCL Process Continuing Execution of an NCL Process Continuing Execution During a debug session, when execution is temporarily suspended at a breakpoint, of an NCL Process you can resume execution using either the DEBUG RESUME command or continuing execution using the DEBUG STEP command.
Debugging an NCL Process Continuing Execution of an NCL Process Resuming Execution to the Next Breakpoint The DEBUG RESUME command allows you to resume execution of a currently suspended NCL process to the next breakpoint or until the NCL process terminates.
Debugging an NCL Process Continuing Execution of an NCL Process Stepping at the Current Nesting Level After suspending execution at statement 16 in the ZEX0902N NCL procedure, the following screen shows the results of stepping at the current nesting level: (08:20) --------------------- OPERATOR CONTROL SERVICES ---------------------DEBUG STEP ---| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10+| NNM1902 NCL 000581 SUSPENDED AT ZEX0902N.17 LINE 35 DEBUG STEP NNM1902 NCL 000581 SUSPENDED AT ZEX0902N.
Debugging an NCL Process Continuing Execution of an NCL Process Stepping Into a Nested Procedure or Function After suspending execution at statement 16 in the ZEX0902N NCL procedure, the following screen shows the results of stepping into the next lower nesting level: (08:17) --------------------- OPERATOR CONTROL SERVICES ---------------------DEBUG STEP NEXT=IN NNM1902 NCL 000581 SUSPENDED AT ZEX0902N.TOP_TITLE.1 LINE 47 DEBUG STEP NNM1902 NCL 000581 SUSPENDED AT ZEX0902N.TOP_TITLE.
Debugging an NCL Process Continuing Execution of an NCL Process Stepping out of a Nested Procedure or Function After suspending execution at statement 16 in the ZEX0902N NCL procedure, the following screen shows the results of stepping into the next lower nesting level and then immediately out to the next higher nesting level: (08:12) --------------------- OPERATOR CONTROL SERVICES ---------------------DEBUG STEP NEXT=IN NNM1902 NCL 000581 SUSPENDED AT ZEX0902N.TOP_TITLE.
Debugging an NCL Process Continuing Execution of an NCL Process Stepping a Specified Number of Steps The following screen shows the results of stepping through a specified number of steps at the current nesting level after suspending execution at statement 16 in the ZEX0902N NCL procedure: (13:46) --------------------- OPERATOR CONTROL SERVICES ---------------------DEBUG STEP NEXT=4 ---| 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10+| 1 : NNM1902 NCL 001506 SUSPENDED AT ZEX0902N.
Debugging an NCL Process Continuing Execution of an NCL Process Automatically Displaying Source Code By using the DEBUG SOURCE command with the ON operand, the DEBUG STEP command displays successive lines of NCL code in decompiled source format, as well as in line number format. By using the DEBUG SOURCE command with the OFF operand, the DEBUG STEP command displays successive lines of NCL code in line number format only.
Debugging an NCL Process Stopping a Debug Session Stopping a Debug The DEBUG STOP command stops a debug session. You can stop debugging either Session one or more specific NCL processes, or all NCL processes. Stopping the Debugging of a Specific NCL Process To stop debugging one or more specific NCL processes, you must use the DEBUG STOP ID=ncl-id command.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Debugging an NCL Process From Start to Finish Purpose of the NCL Procedure This subsection shows how to debug an NCL process from start to finish. To do so, it uses the ZEX0904N NCL procedure, shown later. The ZEX0904N NCL procedure has a single bug that you are going to locate. The purpose of the ZEX0904N NCL procedure is to display the (Gregorian) calendar of a specified month in a specified year.
Debugging an NCL Process Debugging an NCL Process From Start to Finish IF DATECONV( 11, &year"/02/28", 11, 1 ) == &year"/02/29" THEN &days.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Expected Output of the NCL Process The following screen from ZEX0905N (the corrected version of ZEX0904N, listed later in this section) shows the expected (correct) output from displaying the calendar: (06:36) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0905N 02 2020 Calendar for: FEB 2020 Sun Mon Tue Wed Thu Fri Sat 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 NNM1005
Debugging an NCL Process Debugging an NCL Process From Start to Finish Current Output of the NCL Process The following screen from ZEX0904N shows the current (incorrect) output from displaying the calendar: (06:35) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX0904N 02 2020 Calendar for: FEB 2020 Sun Mon Tue Wed Thu Fri Sat 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 MSG QUEUED ------------------ NonStop NET/MASTER D30 ---------------- -------M=> This screen shows that th
Debugging an NCL Process Debugging an NCL Process From Start to Finish Before continuing with this analysis, read the source code that draws the calendar and list the variables used to draw the calendar: Variable Contains &DAY The value of the first day of the month. This variable is used as a loop counter. Its value should vary from 1 through 29. The number of days in the month. Its value should be fixed at 29. The numeric equivalent of the day of the week at which the month starts.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step-by-Step Debugging of the NCL Process The following steps show one possible sequence you can use to debug the ZEX0904N NCL process. Step 1 Define local equate commands and function keys that abbreviate lengthy DEBUG commands, as discussed earlier in this section. Step 2 Start the debug session by using the DEBUG START command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 3 Display the source code by using the DEBUG SOURCE command, as shown in the following four screens. It is useful to display and examine all the source code for errors, if the source code does not span many screens. Notice that each statement is preceded by both a line number and a statement number and that line numbers and statement numbers do not usually correspond.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Screen 2 of 4 (06:48) --------------------- OPERATOR CONTROL SERVICES ---------------------NNM1927 NCL 000670 22 17 0 0 &DAYS.09 = "30" NNM1927 NCL 000670 23 18 0 0 &DAYS.10 = "31" NNM1927 NCL 000670 23 19 0 0 &DAYS.11 = "30" NNM1927 NCL 000670 23 20 0 0 &DAYS.12 = "31" NNM1927 NCL 000670 25 21 0 0 IF DATECONV( "11", &YEAR||"/02/28", "11", 1 )==&YEAR||"/02/29" NNM1927 NCL 000670 26 22 3 0 THEN &DAYS.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Screen 4 of 4.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 4 Set four breakpoints by using the DEBUG BREAKPOINT command, as shown in the following screen. Set a breakpoint at statement 42, to check the values of all variables after the calendar line is drawn. Set a breakpoint at statement 44, to check the values of variables at the beginning of the DO loop that constructs the display line.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 5 Display the source code at statement 42, the current statement, by using the DEBUG SOURCE command, as shown in the first of the following two screens. Display the values of all variables, by using the DEBUG DISPLAY command, as shown in both of the following two screens. In particular, examine the values of all variables and notice that the variables appear to have their correct values.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Screen 2 of 2 (07:07) --------------------- OPERATOR CONTROL SERVICES ---------------------NNM1921 NCL 000670 VBL LINELENGTH VAL "" NNM1921 NCL 000670 VBL MONTH VAL "02" NNM1921 NCL 000670 VBL START VAL "2020/02/01" NNM1921 NCL 000670 VBL YEAR VAL "2020" NNM0999 *END* DEBUG RESUME NNM1905 NCL 000670 RESUMED NNM1902 NCL 000670 SUSPENDED AT ZEX0904N.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 6 Display the source code at statement 44, by using the DEBUG SOURCE command, as shown in the following screen. Display the values of the variables used to draw the calendar, by using the DEBUG DISPLAY command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 7 Display the source code at statement 47, by using the DEBUG SOURCE command, as shown in the following screen. Display the values of the variables used to draw the calendar, by using the DEBUG DISPLAY command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 8 Display the source code at statement 44, by using the DEBUG SOURCE command, as shown in the following screen. Display the values of the variables used to draw the calendar, by using the DEBUG DISPLAY command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 9 Display the source code at statement 47, by using the DEBUG SOURCE command, as shown in the following screen. Display the values of the variables used to draw the calendar, by using the DEBUG DISPLAY command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Resume execution to the next breakpoint, by using the DEBUG RESUME command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 10 Display the source code at statement 47, by using the DEBUG SOURCE command, as shown in the following screen. Display the values of the variables used to draw the calendar, by using the DEBUG DISPLAY command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Resume execution to the next breakpoint, by using the DEBUG RESUME command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 11 Repeat Step 10, modifying the value of &LINELENGTH to the correct length of &LINE, until the DEBUG DISPLAY command shows that the length of &LINE is 35 characters and the value of &LINELENGTH is 35 characters, as shown in the following screen. Resume execution to the next breakpoint, by using the DEBUG RESUME command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Step 12 Stop debugging the NCL process and the primary processing environment environment associated with the OCS window, by using the DEBUG STOP command, as shown in the following screen. Use FUP to copy ZEX0904N to a new NCL procedure, ZEX0905N, as shown in the following screen. Edit the ZEX0905N NCL procedure and correct the suspected bug, by using the EDIT command, as shown in the following screen.
Debugging an NCL Process Debugging an NCL Process From Start to Finish &line = COPIES( " ", &first - 1 ) /* Get numbers of days in month */ &days = &days.
Debugging an NCL Process Debugging an NCL Process From Start to Finish Another Solution for the NCL Process Another way of rewriting the source code that draws the calendar in the ZEX0904N NCL procedure so that it produces correct output is the following: /* Draw calendar */ /* Heading lines */ SAY "Calendar for: "SUBSTR( DATECONV( 11, &start, N ), 4 ) SAY "Sun Mon Tue Wed Thu Fri Sat" /* Construct display line up to starting point of first day */ &line = COPIES( " ", &first - 1 ) /* Get numbers of days i
10 Working With Mapping Services This section discusses the service provided by NonStop NET/MASTER Management Services (MS) called Mapping Services. This service enables the manipulation of data by NCL processes regardless of structure or format. The section discusses the three components in Mapping Services processing—maps, mapped data object (MDO) variables, and NCL procedures. This section does not discuss the structure of standard maps or how to create and use a user-defined map.
Working With Mapping Services Components in Mapping Services Processing Components in There are three main components in Mapping Services processing. The components Mapping Services are briefly discussed here and discussed in detail throughout this section. Processing Maps Mapped data object (MDO) variables NCL procedures Maps describe the structure of MDO variables. MDO variables contain data. The data in an MDO variable is accessed from NCL procedures using certain verbs.
Working With Mapping Services Components in Mapping Services Processing Note NCL Procedures Example of Mapping Services Processing An MDO variable can be either a stem or compound variable. Refer to the discussion on variables in the NonStop NET/MASTER NCL Reference Manual for the syntax of variables in general and stem and compound variables in particular. You can write NCL procedures that access and manipulate the data contained in MDO variables.
Working With Mapping Services Components in Mapping Services Processing 3. Type the second NCL procedure as shown, calling it ZEX1002N: zex1002n: PROCEDURE /* Sends a single message to an OCS window */ WRITE COLOR=WHITE, MON=YES, NRD=OPER, DATA=TEST An OPER NRD message END zex1002n 4. Execute ZEX1002N from the OCS command input line by using the following command: START ZEX1002N 5.
Working With Mapping Services Components in Mapping Services Processing This variable is called a message profile variable. The names of all the structures and substructures contained in the MDO variable begin with this stem. Lines 6 through 14 show the result of using the SAY core statement to name and display the contents of some of the substructures contained in the MDO variable. Mapping Services uses the map $MSG to interpret the contents of the MDO variable. Note The value of &$MSG.SOURCE.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The Structure of The data item described by a map is stored in an MDO variable. In general, an MDO Mapped Data Object variable consists of a header and a single data structure, called an element, where an (MDO) Variables element consists of a header followed by a data component. The data component may consist of other (enclosed) elements inside an outer (enclosing) element or other data structures called groups and fields.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The Header of an MDO Variable All MDO variables have a header. An MDO variable header identifies the beginning of an MDO variable. A header consists of two parts: a length field and a key field. Figure 10-1 shows the structure of the header in an MDO variable mapped by the map $MSG. Figure 10-1.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The length field of an MDO variable header contains internal Mapping Services data. You cannot directly access the length field of an MDO variable header from an NCL procedure.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The Key Field of an MDO Variable Header The key field of an MDO variable header uniquely identifies the map used to access the MDO variable. The value contained in the key field is the name of the map that Mapping Services uses to interpret the MDO variable. The name of the map in Figure 10-1 is $MSG. This is called a symbolic name. The symbolic name of a map is represented internally in an MDO variable.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables Referring to a Whole MDO Variable From NCL A stem variable is a simple or complex variable that ends with a period (.). A stem is used as a prefix for compound variables. Syntactically, MDO variables are compound variables. You use the stem of an MDO variable from an NCL procedure to refer to the whole MDO variable. Referring to the stem refers to all compound variables under the stem.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables Figure 10-2. Header of an Element in an MDO Variable Header Element Length Length Field Key Field len $MSG (02) 4 byte 4 byte Length of Length Field Element Symbolic Name Element Key Value Length of Key Field 004 The Length Field of an Element Header The length field of an element in an MDO variable contains the length of the whole element.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The length field of an element header contains internal Mapping Services data. You cannot directly access the length field of an element header from an NCL procedure.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The Key Field of an Element Header The key field of an element in an MDO variable uniquely identifies the element. The value contained in the key field represents the encoded name of the element definition that Mapping Services uses to interpret the element. The name of the definition in Figure 10-2 is MSGATTR. This is called a symbolic name.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The following MSGPROC NCL procedure refers to an element in an MDO variable: zex1007n: PROCEDURE /* MSGPROC procedure to analyze elements */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO SAY "&$MSG.MSGATTR is "&$msg.msgattr SAY "&$MSG.MSGATTR. is "&$msg.msgattr.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables This example also shows, as with whole MDO variables, that it is generally not useful to display the contents of an enclosed element such as MSGATTR. As a general rule, it is only useful to refer to an enclosing element to copy its contents to another variable. Referring to an enclosing element allows you to copy large blocks of data from one variable to another.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables Figure 10-3.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables Each element inside an enclosing element is interpreted as another element. It has a symbolic name provided by the map that is used to interpret it. Symbolic names among elements at the same level must be unique. Since elements are hierarchical and symbolic names are unique at the same level, you can uniquely identify and refer to an enclosed element from an NCL procedure.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The following examples refer to specific repeated elements: &$EMS.MSGATTR.FLD{1} &$INT.MSGATTR.FLD{2} &$LOG.MSGATTR.FLD{3} &$MSG.MSGATTR.FLD{4} Note /* /* /* /* Refers Refers Refers Refers to to to to 1st 2nd 3rd 4th FLD FLD FLD FLD element element element element */ */ */ */ The {1} is not required for the first occurrence of a repeated element; this is the default.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The following MSGPROC NCL procedure reads a message, assigns values to fields in an element that can be repeated, and displays the modified message on an OCS window: zex1008n: PROCEDURE /* MSGPROC procedure to create a repeated element */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO &$msg.msgattr.fld{1}.offset = 8 &$msg.msgattr.fld{1}.length = 8 &$msg.msgattr.fld{1}.color = "TURQUOISE" &$msg.msgattr.fld{1}.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables A group may have a fixed length or a variable length. A variable length group extends to the end of the group in which it is enclosed, or, if it is an outermost group, to the end of the element in which it is defined. Fields in Elements A field is the most fundamental unit of an MDO variable. Fields contain the basic units of meaningful data in an MDO variable.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables The following MSGPROC NCL procedure reads a message, assigns values to fields in an element that can be repeated, and displays the modified message on an OCS window: zex1009n: PROCEDURE /* MSGPROC procedure to display fields */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO &$msg.msgattr.fld{1}.offset = 8 &$msg.msgattr.fld{1}.length = 8 &$msg.msgattr.fld{1}.color = "TURQUOISE" &$msg.msgattr.fld{1}.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables To obtain a symbolic name, specify an MDO variable name without a number sign, for example: &$MSG.MSGATTR.DISPLAY.COLOR The following MSGPROC NCL procedure reads a message, assigns different colors to the &$MSG.MSGATTR.DISPLAY.
Working With Mapping Services The Structure of Mapped Data Object (MDO) Variables After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services Verbs and MDO Variable Access Verbs and MDO Verbs manipulate data using variables. When a verb accesses data in a variable, it uses Variable Access keywords that support variable access—the ARGS, VARS, RANGE, GENERIC, BYNAME, MERGE, OVERLAY, DATA, MDO, and MAP keywords. MDO data is stored in MDO variables. You use the MDO and MAP keywords in verbs to access MDO variables and maps.
Working With Mapping Services The ASSIGN and DROP Verbs The following examples use the MDO operand to specify MDO variables: ASSIGN MDO=&abcdef. MAP=$SEC ASSIGN MDO=&XYZ_1. ASSIGN MDO=&MY_VAR. FROM MDO=&$INT. EMSALERT MDO=&my_ems. FILE ADD ID=INPUT_1 MDO=&record. FILE GET ID=FILE1 MDO=&file_rec. SECCALL UPDATE USERID=NNMABC MDO=&ums_record. The MAP Operand The MAP operand is used by some verbs to specify the name of the map used to analyze data in an MDO variable.
Working With Mapping Services The ASSIGN and DROP Verbs Format 1 of the ASSIGN Verb Format 1 of the ASSIGN verb is the default form of the verb (where OPT=VALUE follows the ASSIGN keyword). Creating an MDO Variable MDO variables can be created in two ways—automatically by Mapping Services as a result of certain verbs or explicitly by using the ASSIGN verb. Table 10-2 lists the verbs that automatically create MDO variables. Table 10-2.
Working With Mapping Services The ASSIGN and DROP Verbs Table 10-3 lists the verbs that can use an MDO variable after you explicitly create the MDO variable using the ASSIGN verb. You must use the ASSIGN verb to create MDO variables before use by the verbs listed in this table. Table 10-3. Verbs That Can Use an MDO Variable After the Variable Is Created Verb Comment EMSSEND Sends a message from NCL to the EMS collector using the stem name you specify.
Working With Mapping Services The ASSIGN and DROP Verbs The following NCL procedure uses the ASSIGN verb to create an MDO variable, &ABC., which is mapped by the map $MSG: zex1011n: PROCEDURE /* Creates an MDO variable using ASSIGN */ SAY Creating an MDO variable with map $MSG ASSIGN MDO=&abc. OPT=VALUE MAP=$MSG SAY Creating fields in the MDO variable &abc.text = "A test message" &abc.msgattr.display.color = RED &abc.msgattr.display.hlite = NONE &abc.msgattr.display.
Working With Mapping Services The ASSIGN and DROP Verbs Deleting an MDO Variable You can delete an MDO variable in two ways: using the DROP verb or using the ASSIGN verb. The following example of the DROP verb deletes an MDO variable: DROP VARS=&abc. The following syntax of the ASSIGN verb deletes an MDO variable: ASSIGN [ OPT=VALUE ] MDO=variable-name The following example produces the same result as the preceding example: ASSIGN OPT=VALUE MDO=&abc.
Working With Mapping Services The ASSIGN and DROP Verbs The following screen shows the results of executing the procedure: (15:15) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1012N Creating an MDO variable with map $MSG Creating fields in the MDO variable Displaying fields in the MDO variable Text is A test message Color is RED Hlite is NONE Intens is NORMAL Deleting an MDO variable Attempting to display MDO variable Text is Color is Hlite is Intens is NNM1005 START ZEX101
Working With Mapping Services The ASSIGN and DROP Verbs The following NCL procedure uses the ASSIGN verb to create an MDO variable, &ABC., that is interpreted by the map $MSG: zex1013n: PROCEDURE /* Assigns data to an MDO variable */ ON ERROR DO SAY "An error has occurred" SAY "Line is "&SYS.ERROR.LINE SAY "Statement is "&SYS.ERROR.STMT_NAME SAY "Condition is "&SYS.ERROR.COND SAY "Assigning a new value to variable" IF &SYS.ERROR.STMT_NAME = "WRITE" THEN ASSIGN MDO=&abc.
Working With Mapping Services The ASSIGN and DROP Verbs The following screen shows the results of executing the procedure: (07:30) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1013N Creating an MDO variable with map $MSG &ABC. is ABCD An error has occurred Line is 16 Statement is WRITE Condition is VARIABLE_ERROR Assigning a new value to variable &ABC.TEXT is WXYZ NNM1005 START ZEX1013N PROCESSING COMPLETE.
Working With Mapping Services The ASSIGN and DROP Verbs The following MSGPROC NCL procedure reads a message using the MSGREAD verb into the MDO variable, &$MSG.: zex1014n: PROCEDURE /* MSGPROC procedure that transfers data from */ /* one MDO variable to another */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO ASSIGN MDO=&abc. MAP=$MSG ASSIGN MDO=&abc. FROM MDO=&$MSG. SAY "&ABC.TEXT is "&abc.text SAY "&ABC.MSGATTR.DISPLAY.COLOR is "&abc.msgattr.display.color SAY "&ABC.MSGATTR.DISPLAY.
Working With Mapping Services The ASSIGN and DROP Verbs Transferring Data From Ordinary Variables to an MDO Variable You can transfer data from ordinary variables to an MDO variable using the following syntax of the ASSIGN verb: ASSIGN [ OPT=VALUE ] MDO=variable-name [ MAP=map-name ] FROM { ARGS [ RANGE=( start,end ) ] | VARS={ input-vars-list | variable* } [ RANGE=( start,end ) | GENERIC ] } ] The following NCL procedure transfers data from the ordinary variables, &VAR1, &VAR2, and &VAR3 to the MDO variab
Working With Mapping Services The ASSIGN and DROP Verbs The following screen shows the results of executing the procedure: (07:35) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1015N &VAR1 is One &VAR2 is Two &VAR3 is Three &ABC1. ($MSG) is OneTwoThree &ABC2. ($NCL) is . . . One . Two . Three &ABC3. ($SEC) is OneTwoThree &ABC4. ($SPI) is OneTwoThree $NCL is the exception: display using map names &ABC2.DATALIST.DATA{1} is One &ABC2.DATALIST.DATA{2} is Two &ABC2.DATALIST.
Working With Mapping Services The ASSIGN and DROP Verbs The following NCL procedure transfers data from fields in the MDO variable &$MSG. to ordinary variables: zex1016n: PROCEDURE /* Transfers data: MDO variables to ordinary variables */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO ASSIGN VARS=&color FROM MDO=&$MSG.MSGATTR.DISPLAY.COLOR ASSIGN VARS=&hlite FROM MDO=&$MSG.MSGATTR.DISPLAY.HLITE ASSIGN VARS=&intens FROM MDO=&$MSG.MSGATTR.DISPLAY.INTENS ASSIGN VARS=&alarm FROM MDO=&$MSG.MSGATTR.
Working With Mapping Services The ASSIGN and DROP Verbs Using the map $NCL allows you to assign data from ordinary variables to an MDO variable and from an MDO variable to ordinary variables as required. This allows you to easily manipulate data to and from mapped user databases (UDBs), which store ordinary variables in a form mapped by the map $NCL.
Working With Mapping Services The ASSIGN and DROP Verbs Switching Maps You can switch the map that is used to interpret the data in an MDO variable by using the following syntax of the ASSIGN verb: ASSIGN [ OPT=VALUE ] MDO=variable-name MAP=map-name The following example directs Mapping Services to use the map $SEC (rather than the usual map $MSG) to interpret data in the MDO variable &$MSG.: ASSIGN OPT=VALUE MDO=&$MSG.
Working With Mapping Services The ASSIGN and DROP Verbs The following MSGPROC NCL procedure reads a message and uses the ASSIGN verb to obtain the name of the map used to interpret the MDO variable into which the message is placed: zex1018n: PROCEDURE /* MSGPROC procedure to trap a message and display */ /* its map name */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO ASSIGN OPT=MAPNAME VARS=&mapname FROM MDO=&$MSG.
Working With Mapping Services The ASSIGN and DROP Verbs Obtaining Element Names in a Map You can obtain the names of the elements defined in a map at the specified level using the following syntax of the ASSIGN verb: ASSIGN OPT=MAPELEMENTS { ARGS [ RANGE=( start,end ) ] | VARS={ output-vars-list | variable* } [ RANGE=( start,end ) ] } FROM MDO=variable-name The following MSGPROC NCL procedure reads a message and uses the ASSIGN verb to obtain element names: zex1019n: PROCEDURE /* MSGPROC procedure to trap
Working With Mapping Services The ASSIGN and DROP Verbs After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The ASSIGN and DROP Verbs The following MSGPROC NCL procedure reads a message and uses the ASSIGN verb to obtain field names in a map: zex1020n: PROCEDURE /* MSGPROC procedure to trap a message and display */ /* field names in a map */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO ASSIGN OPT=MAPFIELDS VARS=&mapfields*, FROM MDO=&$MSG.MSGATTR.DISPLAY SAY "Fields in map $MSG.MSGATTR.DISPLAY are" DO &i = 1 TO &SYS.
Working With Mapping Services The ASSIGN and DROP Verbs Obtaining Element Names in an MDO Variable You can obtain the names of the elements present in an MDO variable at the specified level using the following syntax of the ASSIGN verb: ASSIGN OPT=MDOELEMENTS { ARGS [ RANGE=( start,end ) ] | VARS={ output-vars-list | variable* } [ RANGE=( start,end ) ] } FROM MDO=variable-name Only the names of those elements present within the specified MDO variable are returned.
Working With Mapping Services The ASSIGN and DROP Verbs After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The ASSIGN and DROP Verbs The following MSGPROC NCL procedure reads a message and uses the ASSIGN verb to obtain the names of the fields that are present: zex1022n: PROCEDURE /* MSGPROC procedure to trap a message and display */ /* field names in an MDO variable */ DO FOREVER MSGREAD VARS=&word* IF &word1 = "TEST" THEN DO ASSIGN OPT=MDOFIELDS VARS=&mdofields*, FROM MDO=&$MSG.MSGATTR.FLAGS SAY "Fields under &$MSG.MSGATTR.FLAGS are" DO &i = 1 TO &SYS.
Working With Mapping Services The ASSIGN and DROP Verbs Obtaining Information About Repeated Elements in an MDO Variable You can obtain information about repeated elements in an MDO variable at the specified level using the following syntax of the ASSIGN verb: ASSIGN OPT=MDOCOUNTS { ARGS [ RANGE=( start,end ) ] | VARS={ output-vars-list | variable* } [ RANGE=( start,end ) ] } FROM MDO=variable-name The following MSGPROC NCL procedure reads a message and uses the ASSIGN verb to obtain information about vari
Working With Mapping Services The ASSIGN and DROP Verbs After following the steps outlined earlier in this section to type this NCL procedure and install it as your active MSGPROC procedure, execute the ZEX1002N NCL procedure to send a message to your OCS window.
Working With Mapping Services The ASSIGN and DROP Verbs (This page left intentionally blank) 10–52 106160 Tandem Computers Incorporated
11 Standard and User-Defined Maps This section discusses the structure of standard maps and how to create and use a user-defined map. A standard map is a map supplied with NonStop NET/MASTER MS to access data structures that are an integral part of NonStop NET/MASTER MS. A user-defined map is a map that you create to access data structures that you define. Table 11-1 summarizes the verbs discussed in this section. These are verbs that support access to Mapping Services and data in MDO variables. Table 11-1.
Standard and User-Defined Maps Table 11-2 summarizes the standard maps discussed in this section. Table 11-2. Standard Maps Map Description $MSG Used to interpret the data in an MDO variable that contains a message traveling to, from, or within NonStop NET/MASTER MS. Used to interpret the data in an MDO variable that contains a record being written to or read from a mapped user database (UDB).
Standard and User-Defined Maps The Standard Map $NCL The Standard Map The standard map $NCL is used by the FILE and WRITE verbs. Figure 11-1 shows the $NCL structure of the map $NCL. It shows that data structured by this map corresponds to the following MDO variable: &stem-name.DATALIST stem-name specifies the name of the stem of the MDO variable that holds the record. Fields in data structured by this map correspond to the following repeated MDO variables: … &stem-name.DATALIST.DATA{1} &stem-name.
Standard and User-Defined Maps The Standard Map $NCL Figure 11-1. The Map $NCL 1. MDO Header len 4 byte $NCL (01) 4 byte 2.
Standard and User-Defined Maps The Standard Map $MSG The Standard Map The standard map $MSG is used by the message verbs. The message verbs—EMS*, $MSG INT*, LOG*, and MSG*—control the flow of messages traveling to, from, and within NonStop NET/MASTER MS. The map used by these verbs to interpret the data in an MDO variable that contains a message is $MSG. (Section 2, “NCL Summary,” discusses the meaning of the asterisk (*) following the letters EMS, INT, LOG, and MSG.
Standard and User-Defined Maps The Standard Map $MSG The values that a message profile variable can contain are listed in the NonStop NET/MASTER NCL Reference Manual. Figure 11-2.
Standard and User-Defined Maps The Standard Map $MSG Figure 11-2.
Standard and User-Defined Maps The Standard Map $MSG Figure 11-2. The Map $MSG (Page 3 of 5) Source Information len 2 byte SOURCE (07) 2 byte 25 1 byte len 1 byte TIME (09) 1 byte ORIG (15) 1 byte time (yyyy/mm/dd hh:mm:ss.
Standard and User-Defined Maps The Standard Map $MSG Figure 11-2.
Standard and User-Defined Maps The Standard Map $MSG Figure 11-2.
Standard and User-Defined Maps The Standard Map $SPI The Standard Map The standard map $MSG is used by the message verbs. Event Management Service $SPI (EMS) event messages arriving at NonStop NET/MASTER MS, from Tandem subsystems such as Expand, Pathway, and SNAX/CDF, always contain SPI tokens. When an event message arrives at NonStop NET/MASTER MS, NonStop NET/MASTER MS creates two structures.
Standard and User-Defined Maps The Standard Map $SPI SPI to MDO Conversion Rules When an event message containing SPI tokens arrives at NonStop NET/MASTER MS, NonStop NET/MASTER MS converts the SPI tokens to a structure that Mapping Services can understand using the map $SPI. It converts the SPI tokens using a series of rules. SPI to MDO Conversion Rule 1 NonStop NET/MASTER MS makes an EMSTEXT system call.
Standard and User-Defined Maps The Standard Map $SPI SPI to MDO Conversion Rule 2c. NonStop NET/MASTER MS converts all subordinate fields in a SPI token to fields that are subordinate to the SPI token name in an MDO variable. (The SPI token name is effectively regarded as an element name.
Standard and User-Defined Maps The Standard Map $SPI The following table shows enumerated and unenumerated values for some event numbers and symbolic names defined by the Expand subsystem in a message that is read by the MSGREAD verb: Expand Event Number Value MDO Variable Name (&$MSG.SPI.TANDEM. begins all variable names.) EXP0003 3 ZEXP_ENM_IO_BUS_ERR 4 ZEXP_ENM_DEV_ERR 6 ZEXP_ENM_DEV_UP 7 ZEXP_ENM_DEV_DOWN ZEMS_TKN_EVENTNUMBER.
Standard and User-Defined Maps The Standard Map $SPI The second method, using two assignment statements, uses two simple variables. The first assignment statement assigns the name of the subject of a message read by the MSGREAD verb into the simple variable &A. The second assignment statement uses &A in an MDO variable to then assign the value of the subject into the simple variable &B: &a = &$MSG.SPI.TANDEM.ZEMS_TKN_SUBJECT_MARK &b = &$MSG.SPI.
Standard and User-Defined Maps The Standard Map $SPI Table 11-4. SPI Tokens Converted to External Form in an MDO Variable (Page 1 of 3) SPI Tokens and Fields Conversion Method Used Result of Conversion to External Form ZSPI-TDT-FNAME Converted to external form using the Guardian FNAMECOLLAPSE procedure call. (FNAMEEXPAND converts to internal form.) Converted to external form using the Guardian FNAME32COLLAPSE procedure call. (FNAME32EXPAND converts to internal form.
Standard and User-Defined Maps The Standard Map $SPI Table 11-4. SPI Tokens Converted to External Form in an MDO Variable (Page 2 of 3) SPI Tokens and Fields Conversion Method Used Result of Conversion to External Form ZSPI-TDT-UINT Not converted to external form unless enumerated and in a shared token, in which case it is converted to long with the high 16 bits as the subsystem number. (Removing the high 16 bits converts to internal form.
Standard and User-Defined Maps The Standard Map $SPI Table 11-4. SPI Tokens Converted to External Form in an MDO Variable (Page 3 of 3) SPI Tokens and Fields Conversion Method Used Result of Conversion to External Form DATA-TYP-INT4 DATA-TYP-FLOAT64 DATA-TYP-BOOL DATA-TYP-REAL-ENUM Converted to NCL floating point format. Converted to NCL floating point format. Converted to 0 or 1.
Standard and User-Defined Maps The Standard Map $SPI Detecting a Message With SPI Tokens After you read a message using the EMSREAD, INTREAD, LOGREAD, or MSGREAD verb, you can easily detect whether it contains SPI tokens. If a message does not contain SPI tokens, the SPI element is not present in the message. Conversely, if a message does contain SPI tokens, the SPI element is present in the message.
Standard and User-Defined Maps The Standard Map $SPI 4. Type the second NCL procedure as shown, calling it ZEX1102N: zex1102n: PROCEDURE /* MSGPROC procedure to analyze and filter messages with */ /* SPI tokens */ DO FOREVER /* Read message into a single variable */ MSGREAD VARS=&message PARSE=NO /* See if message text contains TEST */ &found = POS(TEST,&message) SELECT /* SPI tokens present and contains TEST */ WHEN &$msg.
Standard and User-Defined Maps The Standard Map $SPI 7. Execute the following commands to ensure that NonStop NET/MASTER MS can receive EMS messages: EMSDIST START EMSCOLL START The EMSDIST START command starts the EMS distributor interface. The EMSCOLL START command starts the EMS collector interface. You can use the STATUS command to confirm that the interfaces have started. 8.
Standard and User-Defined Maps The Standard Map $SPI Screen 2 of 2. (08:12) --------------------- OPERATOR CONTROL SERVICES ---------------------ZEMS_TKN_PIN is 130 ZEMS_TKN_REDUNDANT is 0 ZEMS_TKN_SUPPRESS_DISPLAY is 0 ZEMS_TKN_SYSTEM is 250 ZEMS_TKN_USERID is d ZEMS_TKN_NODENAME is \SYS1 ZEMS_TKN_SUBJECT_MARK is TANDEM.
Standard and User-Defined Maps The Standard Map $SEC The Standard Map The standard map $SEC is used by the SECCALL verbs. The SECCALL verbs— $SEC SECCALL ADD, SECCALL CHANGE, and so on—manipulate user ID definition records in the User ID Management Services (UMS) database. The default map used by these verbs to interpret the data in an MDO variable that contains a record being written to or read from the User ID Management Services (UMS) database is $SEC. Figure 11-3 shows the structure of the map $SEC.
Standard and User-Defined Maps The Standard Map $SEC Figure 11-3. The Map $SEC (Page 1 of 4) 1. MDO Header len 4 byte $SEC (16) 4 byte 2.
Standard and User-Defined Maps The Standard Map $SEC Figure 11-3. The Map $SEC (Page 2 of 4) 3.
Standard and User-Defined Maps The Standard Map $SEC Figure 11-3. The Map $SEC (Page 3 of 4) 4.
Standard and User-Defined Maps The Standard Map $SEC Figure 11-3. The Map $SEC (Page 4 of 4) 5.
Standard and User-Defined Maps User-Defined Maps User-Defined Maps NonStop NET/MASTER MS lets you create and use maps to access data structures that you define. These are called user-defined maps. This subsection discusses the following topics: Why you would create a user-defined map Creating a user-defined map. Using a user-defined map.
Standard and User-Defined Maps User-Defined Maps Creating a User-Defined Map To create a user-defined map, follow these steps: 1. Create a DDL source schema file using DDL statements. 2. Create a DDL data dictionary using the source schema file as input. 3. Create a map definition using the DDL data dictionary as input and add the map definition to the NonStop NET/MASTER MS map file.
Standard and User-Defined Maps User-Defined Maps 02 midinit PIC X(1). END DEF address. 02 street 02 city 02 state 02 zip END PIC PIC PIC PIC DEF date. 02 day 02 month 02 year END PIC 9(2). PIC X(3). PIC 9(2). X(25). X(14). X(3). 9(5). DEF department. 02 depnum. 04 regnum PIC 9. 04 branchnum PIC 9. 02 deptype TYPE ENUM. 89 sales. 89 marketing. 89 admin. 89 education. 89 development. END DEF empdef. 02 empcode 02 empname 02 empaddr 02 empbday 02 empsex 02 empdep 02 emppay OCCURS PIC 9(4). TYPE name.
Standard and User-Defined Maps User-Defined Maps field (DEPTYPE), each of which is at the same level. The DEPNUM group has two fields (REGNUM and BRANCHNUM). The DEPTYPE field defines an enumerated data type. The EMPDEF group is defined using four previously defined data structures (NAME, ADDRESS, DATE, and DEPARTMENT). DATE is used twice: first, for EMPBDAY; second, for EMPPAY. The value of PAYPERIOD determines the number of occurrences (12) of the EMPPAY field. The schema defines one record (EMPREC).
Standard and User-Defined Maps User-Defined Maps The listing also shows that FUP output is produced. FUP can use this output to create a key-sequenced Enscribe file called $DATA2.UDDL.EMPFILE to contain employee information that is mapped by the EMPREC map. Using this file, an NCL process and an external application can easily share access to the same employee data.
Standard and User-Defined Maps User-Defined Maps You can determine whether a map is available for use by using the SHOW MAPS command.
Standard and User-Defined Maps User-Defined Maps Before you attempt to use the user-defined map, it is useful to confirm that the data structures defined using DDL correspond to the data structures you expect in the user-defined map. The following NCL procedure lets you display the groups and fields in a user-defined map. zex1104n: procedure /* Displays a user-defined map */ ASSIGN MDO=&x. MAP=&1 CALL show_map( 0, "" ) SHARE &x.
Standard and User-Defined Maps User-Defined Maps Note Using a User-Defined Map A user-defined map does not have elements, only groups and fields. After you have created a user-defined map, an NCL process can use the map. An NCL process uses a user-defined map as it uses a standard map. That is, it uses the names of substructures within the map to locate data at a certain position in an MDO variable. Section 10, “Working with Mapping Services,” explains how to use MDO variables.
Standard and User-Defined Maps User-Defined Maps /* sequenced file. The UDBCTL OPEN command opens a */ /* file for access by NonStop NET/MASTER.) */ /* It is recommended that KEYEXTR is equal to NO for */ /* files mapped with a user-defined map. */ FILE OPEN FORMAT=MAPPED MAP=&usermap ID=&id KEYEXTR=NO SELECT &SYS.FILE.
Standard and User-Defined Maps User-Defined Maps WHEN 16 THEN SAY "16 "&SYSMSG OTHERWISE SAY Unexpected error END /*select*/ EXIT &SYS.FILE.RC END add_record /* ==================== GET RECORD ==================== */ get_record: PROCEDURE SHARE &usermap,&getmdo. /* Gets one record, mapped by a user-defined map. */ &key = "77 " FILE GET KEY=&key MDO=&getmdo. SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "GET KEY operand value is |"&key"|" SAY "GET &SYS.FILE.KEY value is |"&SYS.FILE.
Standard and User-Defined Maps User-Defined Maps This NCL procedure shows how to refer to data structures in the MDO variable mapped by EMPREC and how to assign data to the groups and fields in the MDO variable. A full name hierarchy is required to refer to a field. Assigning data to a field explicitly assigns data only to that field. The following example assigns the value Smith to the field &ADDMDO.EMPNAME.LASTNAME: &ADDMDO.EMPNAME.LASTNAME = Smith A full name hierarchy is required to refer to a group.
Standard and User-Defined Maps User-Defined Maps 4. Observe the results, as shown in the following two screens: Screen 1 of 2 (11:58) --------------------- OPERATOR CONTROL SERVICES ---------------------UDBCTL OPEN=$DATA2.UDDL.EMPFILE ID=EMPFILE NNM0300 OPEN REQUEST COMPLETE START ZEX1105N 8 Read, write, and delete access 0 Record added PUT KEY operand value is |77 | PUT &SYS.FILE.KEY value is |77 | 0 Record retrieved GET KEY operand value is |77 | GET &SYS.FILE.
Standard and User-Defined Maps User-Defined Maps Screen 2 of 2 (11:58) --------------------- OPERATOR CONTROL SERVICES ---------------------Group DEPNUM is |95| Field BRANCHNUM is |5| Field REGNUM is |9| Field DEPTYPE is |EDUCATION| Field DEPTYPE# is |3| Group EMPNAME is |Smith John A| Field FIRSTNAME is |John | Field LASTNAME is |Smith | Field MIDINIT is |A| Group EMPPAY{1} is |31Jan99| Field DAY is |31| Field MONTH is |Jan| Field YEAR is |99| Group EMPPAY{2} is | | Field DAY is | | Field MONTH is | | Fie
Standard and User-Defined Maps User-Defined Maps The following DEFINITION and RECORD clauses are supported by NonStop NET/MASTER MS: OCCURS PIC[TURE] TACL TYPE data-type TYPE def-name 89 enumeration The following DEFINITION and RECORD clauses are not supported by NonStop NET/MASTER MS: AS CONSTANT DISPLAY EDIT-PIC FILLER HEADING HELP KEYTAG MUST BE NULL OCCURS … DEPENDING ON … REDEFINES SPI-NULL UPSHIFT USAGE [NO]VALUE 66 RENAMES 88 condition-name You can create an Enscribe entry-sequenced, key-sequenced,
Standard and User-Defined Maps User-Defined Maps The following steps show what you should do to work with a file that you create using DDL using its corresponding map: 1. Assign a key for the key-sequenced file as part of the RECORD clause, for example: DEF empdef 02 empcode … END PIC 9(4). RECORD emprec. FILE IS "$DATA2.UDDL.EMPFILE" KEY-SEQUENCED. DEF IS empdef. KEY IS emprec.empcode. END 2.
Standard and User-Defined Maps User-Defined Maps If you do not use the KEY operand in the FILE ADD or FILE PUT verb, the value of the key on the file is the current value of &SYS.FILE.KEY rather than the value in the MDO variable that corresponds to the key you defined using DDL. If the value of &SYS.FILE.KEY is null, a run-time error is raised. When you are reading from an existing file, the value of &SYS.FILE.
Standard and User-Defined Maps User-Defined Maps NonStop NET/MASTER MS stores some TYPE clause data types in internal form different from how they are stored in external form in an MDO variable. Table 11-6 summarizes how TYPE clause data types are treated. Table 11-6. Considerations for TYPE Clause Data Types TYPE Clause Data Type Internal Form External Form BINARY 8 BINARY 8 UNSIGNED BINARY 16 BINARY 16 UNSIGNED BINARY 16, n N.A. N.A. N.A. N.A. Stored as an integer without the decimal point.
Standard and User-Defined Maps User-Defined Maps The following table shows some examples of values that are valid for the specified TYPE clause: TYPE Clause Original Value Reason BINARY 16, 2 123.45 BINARY 16, 2 UNSIGNED 11.11 BINARY 64, 1 756.32 The value of 12345 is greater than -32768 and less than 32767. The value of 1111 is greater than 0 and less than 65535. After 756.32 is rounded down to 756.30, the value of 7563 is greater than -32768 and less than 32767.
Standard and User-Defined Maps User-Defined Maps (This page left intentionally blank) 11–46 106160 Tandem Computers Incorporated
12 Working With Files This section discusses how to work with files—or user databases (UDBs)—from an NCL process.
Working With Files Enscribe File Structures and NCL Table 12-1. Verbs and NonStop NET/MASTER MS Commands Used With Files (Page 2 of 2) Verb or Command Description SHOW UDB command SHOW UDBUSER command Displays the status of user databases (UDBs). Displays information about the users and NCL processes that are currently using user databases (UDB). Associates a user database (UDB) identifier with the name of a file or the names of a pair of files. Closes a user database (UDB) or UDB pair.
Working With Files Enscribe File Structures and NCL Table 12-2. FILE Verbs and Enscribe File Types Supported by NCL Enscribe File Type Structured Unstructured FILE Verb Operation E K R Edit file Guardian.
Working With Files Enscribe File Structures and NCL Entry-Sequenced Files Entry-sequenced files are designed for sequential access. They consist of variable-length records that are always appended to the end of the file in the order in which they are presented. As a result, the records in the file are arranged physically and logically in the order in which they are added to the file. The primary key for records in entry-sequenced files is a record address maintained by Enscribe.
Working With Files Enscribe File Structures and NCL The primary key for records in key-sequenced files is a specified data field within a record. NCL can read from and write to key-sequenced files. Figure 12-4 shows the structure of a record in a key-sequenced file. Figure 12-5 shows some records in a key-sequenced file. Figure 12-4. Record Structure in a Key-Sequenced File CUST_CODE NAME ADDRESS PHONE AGE Primary Key 028 Figure 12-5.
Working With Files User Databases (UDBs) Guardian Processes A Guardian process is a program that is running. NCL can communicate with Guardian processes through standard file-system data transfers. Communication can consist of a simple one-way transfer from the originating NCL process to the destination Guardian process, or a two-way transfer in which the originating NCL process expects a reply from the destination Guardian process.
Working With Files User Databases (UDBs) the file containing the help information you distribute with the application; second, you want users to be able to customize the help information. You can achieve these aims by providing two key-sequenced files with the NCL application, and by opening the files as a UDB pair. Assume that the application has a FIND command, and that the read-only help file in the UDB pair states: The FIND command finds a record that matches the specified criteria.
Working With Files Creating a UDB Creating a UDB Before NCL can work with a single UDB or UDB pair, you must create the single file or two files, respectively. This subsection discusses how.
Working With Files Creating a UDB Creating UDBs From NonStop NET/MASTER MS From NonStop NET/MASTER MS, it is usually most convenient to use FUP to create a UDB or the files in a UDB pair. The following example uses the OPSYS SEND command from the OCS command input line to invoke FUP from NonStop NET/MASTER MS. The example shows two FUP commands—the first creates an entry-sequenced file, and the second purges the file: OPSYS SEND FUP CREATE $DATA.SUBVOL.MYFILE, TYPE E OPSYS SEND FUP PURGE $DATA.SUBVOL.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS Refer to the NonStop NET/MASTER MS Command Reference Manual for more information on the OPSYS and STATUS commands. Controlling Access to After you have created a single UDB or the files in a UDB pair, you must prepare the UDBs by NonStop UDB or UDB pair for system-wide access—that is, prepare it for access by NonStop NET/MASTER MS NET/MASTER MS—before NCL can work with it.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS access the UDB or UDB pair, and provides a logical connection between NCL and a UDB or UDB pair. When you open a single UDB, the UDB ID refers to one file. When you open a UDB pair, the UDB ID refers to both files, which are treated as a single unit. A UDB ID must be from one through eight characters long.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS The following code segment opens MYFILE from an NCL process and assigns the UDB an identifier: … /* Opens the UDB with a UDB ID */ INTCMD "UDBCTL OPEN=$DATA.SUBVOL.MYFILE ID=UDBID1" … The following example assigns the identifier MYFILE2 to the UDBs MYFILE1 and MYFILE2 when you open the UDB pair: UDBCTL OPEN=($DATA.SUBVOL.MYFILE1,$DATA.SUBVOL.MYFILE2) ID=* The preceding example is the same as the following example: UDBCTL OPEN=($DATA.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS The following code segment opens the UDB pair from an NCL process and then assigns the identifier UDBID1 to the UDB pair after the UDB pair is opened: … /* Opens the UDB pair without a UDB ID */ INTCMD "UDBCTL OPEN=($DATA.SUBVOL.MYFILE1,", "$DATA.SUBVOL.MYFILE2)" … /* Assigns a UDB ID to the UDB pair */ INTCMD "UDBCTL ($DATA.SUBVOL.MYFILE1,", "$DATA.SUBVOL.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS Performing a RESET Operation on a Single UDB. To perform a RESET operation on a single UDB before you open it, use the UDBCTL RESET command. The following example performs a RESET operation on MYFILE: UDBCTL RESET=$DATA.SUBVOL.MYFILE To perform a RESET operation on a single UDB when you open it, use the RESET operand of the UDBCTL OPEN command. The following example performs a RESET operation on MYFILE: UDBCTL OPEN=$DATA.SUBVOL.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS Specifying the Guardian User ID Your available Guardian user IDs (GUIDs) are assigned to you by User ID Management Services (UMS). You can determine your current GUID by using the PROFILE command. You can control whether a UDB or UDB pair is opened using your current GUID or the GUID of NonStop NET/MASTER MS when an NCL process uses the FILE OPEN verb. This is controlled by the SWGUID operand of the UDBCTL OPEN command.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS The following example dissociates the UDB from its identifier: UDBCTL STOP=UDBID1 After you dissociate a UDB from its UDB ID, you must assign it a new identifier if you want to make it available to NCL again. The following example assigns the UDB $DATA.SUBVOL.MYFILE a new UDB ID: UDBCTL $DATA.SUBVOL.
Working With Files Controlling Access to UDBs by NonStop NET/MASTER MS 3. Write an NCL procedure called PROC1 that refers to a UDB with the identifier of UDBID1. The NCL procedure has statements such as the following: FILE FILE FILE FILE OPEN ID=UDBID1 FORMAT=MAPPED MAP=$NCL GET ID=UDBID1 OPT=KLT ARGS PUT ID=UDBID1 ARGS CLOSE ID=UDBID1 If the NCL procedure is executed at this stage, all FILE verbs in PROC1 refer to LOGFILE1 since LOGFILE1 is associated with the UDB ID of UDBID1. 4.
Working With Files Displaying UDB Information Displaying UDB After you have opened a UDB or UDB pair, you can use the following NonStop Information NET/MASTER MS commands to display UDB information: SHOW FILES SHOW UDB SHOW UDBUSER These commands are discussed briefly later; refer to the NonStop NET/MASTER MS Command Reference Manual for more information about these commands.
Working With Files Displaying UDB Information Displaying Status Information About UDBs The SHOW UDB command displays information about the status of UDBs, as the following screen shows: (10:55) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW UDB NNM0313 FILENAME FILEID A/U RKP KYL STUS OPTNS NNM0314 \SYS1.$DATA4.ZNNMDATA.ZLGFILE1 LOGFILE1 0 0 44 SYS I NNM0314 \SYS1.$DATA4.ZNNMDATA.ZMAPFILE MDSMAP 0 0 36 SYS NNM0314 \SYS1.$DATA4.ZNNMDATA.MSGDB ZHLPMSG 0 0 10 AVAL I NNM0314 \SYS1.
Working With Files Displaying UDB Information If the SHOW UDB command indicates that a UDB or UDB pair is in error, you can use the error number to determine the cause of the error, and the UDBCTL CLOSE command to close the UDB or UDB pair. The following screen shows a UDB in error and how to use the UDBCTL CLOSE command to close the UDB: (14:39) --------------------- OPERATOR CONTROL SERVICES ---------------------UDBCTL OPEN=MYFILE NNM0309 OPEN FAILED, ERROR=11, UDB=\SYS1.$DATA9.ZNNM.
Working With Files Controlling Access to a UDB or UDB Pair by NCL Controlling Access to After you have created a UDB or UDB pair, opened it for system-wide access from a UDB or UDB Pair by NonStop NET/MASTER MS, and assigned it a UDB ID, then an NCL process can NCL access the UDB or UDB pair and the data contained therein by using the FILE verbs. Table 12-1 summarizes the FILE verbs. Table 12-2 summarizes the FILE verbs and Enscribe file types supported by NCL. These tables appear earlier in this section.
Working With Files Opening a UDB or UDB Pair for Access by NCL Opening a UDB or The FILE OPEN verb opens a UDB or UDB pair for processing by subsequent FILE UDB Pair for Access verbs. You must open a UDB or UDB pair by using the FILE OPEN verb before any by NCL other FILE verb can work with the UDB or UDB pair. Specifying the UDB Identifier The FILE OPEN verb must specify the UDB ID of a UDB or UDB pair when it opens the UDB or UDB pair from an NCL process by using the ID operand.
Working With Files Opening a UDB or UDB Pair for Access by NCL &found = POS("CREATED -",&text) IF &found > 0 THEN DO /* FUP has created a new file */ SAY "Opening UDB for system-wide access" INTCLEAR INTCMD "UDBCTL OPEN="&filename" ID=ZEX1201N" INTREAD INTCONT SAY "Opening UDB from NCL" FILE OPEN ID=ZEX1201N SELECT &SYS.FILE.
Working With Files Opening a UDB or UDB Pair for Access by NCL The name of the file, $DATA2.JOHNNCLS.JNFILE, is entered as the first parameter to the NCL procedure. The NCL process attempts to use FUP to create the file. If FUP is able to create the file, the UDBCTL OPEN command opens the file for system-wide access, the FILE OPEN verb opens the UDB for access from NCL, the FILE CLOSE verb closes the UDB, and the UDBCTL CLOSE command closes the file for access from NonStop NET/MASTER MS.
Working With Files Opening a UDB or UDB Pair for Access by NCL The following code segment illustrates this for a UDB pair: … INTCLEAR INTCMD "UDBCTL OPEN=($DATA.SUBVOL.MYFILE1,", "$DATA.SUBVOL.MYFILE2) ID=UDBID1" INTREAD INTCONT FILE OPEN ID=UDBID1 … FILE GET ID=UDBID1 … After a UDB or UDB pair is assigned a system-wide UDB ID by the UDBCTL command, the NCL process uses one FILE OPEN verb to open the UDB or UDB pair.
Working With Files Opening a UDB or UDB Pair for Access by NCL After a UDB or UDB pair is assigned a system-wide UDB ID by the UDBCTL command, the NCL process uses one FILE OPEN verb to open the UDB or UDB pair. The FILE OPEN verb uses both the UDBID operand, which specifies the system-wide UDB ID of the UDB or UDB pair, and the ID operand, which explicitly assigns a different local file identifier to the UDB or UDB pair. That is, the UDBID operand and the ID operand specify different identifiers.
Working With Files Opening a UDB or UDB Pair for Access by NCL After a UDB or UDB pair is assigned a system-wide UDB ID by the UDBCTL command, the NCL process uses multiple FILE OPEN verbs to open the UDB or UDB pair. Each FILE verb uses both the UDBID operand, which specifies the UDB ID of the UDB or UDB pair, and the ID operand, which specifies a different local file identifier. This allows a UDB or UDB pair to have different local file identifiers.
Working With Files Opening a UDB or UDB Pair for Access by NCL IF &found > 0 THEN DO /* FUP has created a new file */ SAY "Opening UDB for system-wide access" INTCLEAR INTCMD "UDBCTL OPEN="&filename" ID="&id INTREAD INTCONT SAY "Opening UDB from NCL" FILE OPEN UDBID=&id ID=LOCAL_1 SAY UDBID is &id ID is &SYS.FILE.ID FILE OPEN UDBID=&id ID=LOCAL_2 SAY UDBID is &id ID is &SYS.FILE.ID FILE OPEN UDBID=&id ID=LOCAL_3 SAY UDBID is &id ID is &SYS.FILE.
Working With Files Opening a UDB or UDB Pair for Access by NCL Specifying Record Structure When you open a UDB or UDB pair using the FILE OPEN verb, you can specify to NCL how the data is physically organized in each UDB record by using the FORMAT operand. This determines how NCL interprets data when it reads a record from a UDB or UDB pair and writes a record to a UDB or UDB pair. Data in a UDB record can be physically organized in three different formats.
Working With Files Opening a UDB or UDB Pair for Access by NCL The following examples open mapped UDBs using the maps $NCL, $MSG, $SEC (standard maps), and MYMAP (a user-defined map), respectively: FILE FILE FILE FILE OPEN OPEN OPEN OPEN ID=FILEID_1 ID=FILEID_1 ID=FILEID_1 ID=FILEID_1 FORMAT=MAPPED FORMAT=MAPPED FORMAT=MAPPED FORMAT=MAPPED MAP=$NCL MAP=$MSG MAP=$SEC MAP=MYMAP Figure 12-6 shows the structure of a record in a UDB where the data is mapped and the map is $NCL. Figure 12-6.
Working With Files Opening a UDB or UDB Pair for Access by NCL Figure 12-7. Records in a Mapped Entry-Sequenced File Record 1 56 '001D'X 15 '0000'X ADAMS, J.P. Field 1 17 '0000'X EISENHOWER AV Field 2 16 '0000'X 408 414-5999 Field 3 4 '0000'X Record 2 52 Field 4 '001D'X 17 '0000'X JOHNSON, A.B.
Working With Files Opening a UDB or UDB Pair for Access by NCL Figure 12-8. Records in a Mapped Key-Sequenced File 01 56 '001D'X 15 '0000'X ADAMS, J.P. Field 1 17 '0000'X EISENHOWER AV Field 2 16 '0000'X 408 414-5999 Field 3 4 '0000'X 02 52 Field 4 '001D'X 17 '0000'X JOHNSON, A.B. Field 1 10 '0000'X RED RD Field 2 15 '0000'X 929 43-4345 Field 3 6 '0000'X 03 39 Field 4 '001D'X 13 '0000'X JONES, P.
Working With Files Opening a UDB or UDB Pair for Access by NCL Note By default, when you open a disk file, NCL opens it as a mapped UDB using the map $NCL. By default, when you open a file that is not a disk file, such as a Guardian process or a spooler, NCL opens it as an unmapped UDB. The Structure of an Unmapped UDB In a UDB where the data is unmapped, NCL treats the data in each record as a sequence of contiguous bytes. NCL does not interpret the data in an unmapped UDB.
Working With Files Opening a UDB or UDB Pair for Access by NCL Figure 12-10. Records in an Unmapped Entry-Sequenced File 5 10 15 20 25 30 35 40 45 50 55 60 65 ----|----|----|----|----|----|----|----|----|----|----|----|----| ADAMS, J.P. EISENHOWER AV 408 414-5999 JOHNSON, A.B. RED RD 929 43-4345 JONES, P. FIRST ST BOND, J.
Working With Files Opening a UDB or UDB Pair for Access by NCL Figure 12-11. Delimited UDB Record Structure Record 1 RECORD KEY Field 1 'FF'X Field 2 'FF'X Field 3 'FF'X 'FF'X Field 4 'FF'X Field 5 'FF'X Field 1 'FF'X Field 2 'FF'X Field 3 'FF'X Field 4 'FF'X 'FF'X Field 5 'FF'X 'FF'X Null Null Record 2 RECORD KEY 'FF'X Null Null 035 Both entry-sequenced and key-sequenced files can contain delimited records.
Working With Files Opening a UDB or UDB Pair for Access by NCL Figure 12-13. Records in a Delimited Key-Sequenced File 01 ADAMS, J.P. 'FF'X EISENHOWER AV 'FF'X 02 JOHNSON, A.B. 'FF'X 03 JONES, P. 'FF'X FIRST ST 'FF'X 04 BOND, J. 'FF'X ANDERSON DR 'FF'X RED RD 'FF'X 408 414-5999 'FF'X 'FF'X 929 43-4345 'FF'X 'FF'X 30 'FF'X 55 'FF'X 408 43-1239 'FF'X 15 'FF'X 037 Handling the Record Key UDB records have keys.
Working With Files Opening a UDB or UDB Pair for Access by NCL control over the value of a record key when a record is written to an entry-sequenced file. (Remember, you cannot modify an edit file.) You can modify the value of the record key in a key-sequenced file. When NCL writes a record to a key-sequenced file, it automatically constructs the record key of the record from the value of &SYS.FILE.KEY. It constructs the rest of the record from the variables that contain the data.
Working With Files Setting UDB Characteristics Unmapped UDBs. It is recommended that you set KEYEXTR=NO when you are working with an unmapped UDB. If you are working with a key-sequenced file, you must exclude the record key from your calculations when you retrieve a record if you specify that the file is unmapped and set KEYEXTR=YES. In contrast, you must include the record key in your calculations when you retrieve a record if you specify that the file is unmapped and set KEYEXTR=NO. Delimited UDBs.
Working With Files Setting UDB Characteristics INTCLEAR INTCMD "UDBCTL OPEN="&filename" ID="&id INTREAD INTCONT SAY "Opening UDB from NCL" FILE OPEN UDBID=&id ID=LOCAL_1 SAY "Current file is "&SYS.FILE.ID FILE OPEN UDBID=&id ID=LOCAL_2 SAY "Current file is "&SYS.FILE.ID FILE OPEN UDBID=&id ID=LOCAL_3 SAY "Current file is "&SYS.FILE.ID FILE SET ID=LOCAL_2 SAY "Current file is "&SYS.FILE.ID FILE SET ID=LOCAL_1 SAY "Current file is "&SYS.FILE.
Working With Files Setting UDB Characteristics The name of the file, $DATA2.JOHNNCLS.MYFILE, is entered as the first parameter to the NCL procedure. The NCL process attempts to use FUP to create the file.
Working With Files Setting UDB Characteristics The following code segment opens many files and works with each file in turn: … FILE OPEN ID=INPUT_1 FILE OPEN ID=INPUT_2 FILE OPEN ID=INPUT_3 FILE OPEN ID=OUTPUT_1 … FILE SET ID=INPUT_1 … /* do some processing … FILE SET ID=INPUT_2 … /* do some processing … FILE SET ID=INPUT_3 … /* do some processing … FILE SET ID=OUTPUT_1 … /* do some processing … FILE CLOSE ALL … */ */ */ */ This example uses a number of FILE SET statements to identify the current UDB
Working With Files Closing a UDB or UDB Pair for Access by NCL Specifying the Current Record Key The current record key is the value of the last record key that was explicitly identified in a FILE verb. It is the record key with which NCL assumes it is to work if a FILE verb does not explicitly set a record key. You use the KEY operand on a FILE verb to explicitly specify a record key. Identifying a record key is valid only if you are working with key-sequenced UDBs.
Working With Files Working With Entry-Sequenced Files Working With EntrySequenced Files The structure of records in an entry-sequenced file is briefly described earlier in this section. This subsection describes how to work with entry-sequenced files from an NCL process. It does so by presenting a series of code segments that you can use when you create your own NCL procedures. The code segments show the following: How to create an entry-sequenced file from an NCL process.
Working With Files Working With Entry-Sequenced Files Opening the File for Access by NonStop NET/MASTER MS The UDBCTL OPEN command opens an entry-sequenced file for access by NonStop NET/MASTER MS. The following code segment uses the INTCMD verb to execute the UDBCTL OPEN command from an NCL process: … SAY "Opening "&filename INTCMD "UDBCTL OPEN="&filename" ID="&id INTREAD … Opening the File for Access by NCL The FILE OPEN verb opens an entry-sequenced file for access by NCL.
Working With Files Working With Entry-Sequenced Files Adding a Record to a Mapped Entry-Sequenced File The options available to you to add a record to a mapped entry-sequenced file depend on the map used to interpret the data in the file. Mapped Using $NCL. If the data is mapped using the map $NCL, then you have two options to add data to a file. Using the first option to add data to a file mapped by $NCL, you do not have to create an MDO variable that contains the data before adding the data to a file.
Working With Files Working With Entry-Sequenced Files Mapped Using a Map Other Than $NCL. If the data is mapped using a map other than $NCL (such as $MSG, $SEC, or a user-defined map) then you have two options to add the data to a file. The first option applies when an MDO variable is automatically created by NonStop NET/MASTER MS, for example, after an EMSREAD, INTREAD, LOGREAD, or MSGREAD verb reads a message or a SECCALL GET verb retrieves a record from the User ID Management Services (UMS) database.
Working With Files Working With Entry-Sequenced Files The following code segment adds records to a mapped entry-sequenced file: … ASSIGN MDO=&rec. MAP=$NCL /* Allows you to enter 4 fields for 4 records */ DO &rno = 1 TO 4 DO &fno = 1 TO 4 SAY Enter record &rno field &fno CMDLINE "-GO ID="&SYS.NCLID _ PAUSE VARS=&field&fno PARSE=NO END /*&fno do*/ ASSIGN MDO=&rec. MAP=$NCL FROM VARS=&field* SAY "Adding record "&rno" to "&filename FILE ADD MDO=&rec. END /*&rno do*/ … It creates an MDO variable—&REC.
Working With Files Working With Entry-Sequenced Files It uses a DO loop to obtain four records. It uses a nested DO loop to obtain four fields in each record that it places in the ordinary variables—&FIELD*. After data is placed in each variable, the LEFT built-in function ensures that the data in each field is fixed at 20 bytes. Since there are 4 fields in a record, the length of each record is fixed at 80 bytes.
Working With Files Working With Entry-Sequenced Files Table 12-3. Options That Specify Retrieval Direction Option Meaning BWD Retrieves the previous record—either the previous physical record in an entry-sequenced UDB or the previous logical record in a key-sequenced UDB. This terminates generic retrieval (in key-sequenced UDBs). Retrieves the following record—either the following physical record in an entry-sequenced UDB or the following logical record in a key-sequenced UDB.
Working With Files Working With Entry-Sequenced Files Mapped Using a Map Other Than $NCL. If the data is mapped using a map other than $NCL (such as $MSG, $SEC, or a user-defined map), then you must specify the MDO keyword and the name of an MDO variable when you get the record. The FILE GET verb gets a record and places it into the MDO variable using the correct map. The following example uses the FILE GET verb to get a record and place it in the MDO variable &SEC.: FILE GET MDO=&sec.
Working With Files Working With Entry-Sequenced Files The following FILE verbs use length variable specifications to split the following record from an unmapped file: ABC XYZ 123 789 FILE GET ARGS &1 = ABC XYZ 123 789 FILE GET VARS=&A* &A1 = ABC XYZ 123 789 FILE GET VARS=(&A*(1,2),&B*) RANGE=(3,4) &A1 = ABC XYZ 123 789 FILE GET VARS=(&A(2),&B(2),&C(2),&D(2)) &A &B &C &D = = = = AB "C " XY "Z " FILE GET VARS=(&A(1),&B(2),*,&D(1)) &A = A &B = BC &D = X The following code segment gets all records from an
Working With Files Working With Entry-Sequenced Files Getting a Record From a Delimited Entry-Sequenced File When you get a record from a delimited entry-sequenced file, NCL returns the data in a series of variables using the field separators to determine the length and delimit the contents of each field.
Working With Files Working With Entry-Sequenced Files Example—Adding Records to an Entry-Sequenced File The following NCL procedure adds four records to a mapped entry-sequenced file. It obtains the records by pausing and waiting for input typed in at the OCS command input line. One line of input is regarded as one field in a record. Each record has four fields.
Working With Files Working With Entry-Sequenced Files /* ==================== ADD RECORDS ==================== */ add_records: PROCEDURE SHARE &filename,&id /* Gets records from OCS command input line */ /* and adds to file. */ ASSIGN MDO=&rec. MAP=$NCL /* Allows you to enter 4 fields for 4 records */ DO &rno = 1 TO 4 DO &fno = 1 TO 4 SAY Enter record &rno field &fno CMDLINE "-GO ID="&SYS.NCLID _ PAUSE VARS=&field&fno PARSE=NO END /*&fno do*/ ASSIGN MDO=&rec.
Working With Files Working With Entry-Sequenced Files The following screen shows the results of executing the procedure: (11:29) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1204N $DATA2.JOHNNCLS.MESUDB Creating file $DATA2.JOHNNCLS.MESUDB Opening $DATA2.JOHNNCLS.
Working With Files Working With Entry-Sequenced Files WHEN 16 THEN SAY "16 "&SYSMSG OTHERWISE SAY Unexpected error END /*select*/ END open_file /* ==================== GET RECORDS ==================== */ get_records: PROCEDURE SHARE &filename,&id /* Get records and displays them on OCS window */ ASSIGN MDO=&rec. MAP=$NCL FILE GET MDO=&rec. SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.
Working With Files Working With Single Key-Sequenced Files Working With Single Key-Sequenced Files The structure of records in a key-sequenced file is briefly described earlier in this section. This subsection describes how to work with single key-sequenced files from an NCL process. It does so by presenting a series of code segments that you can use when you create your own NCL procedures. The code segments show the following: How to create a key-sequenced file from an NCL process.
Working With Files Working With Single Key-Sequenced Files Opening the File for Access by NonStop NET/MASTER MS The UDBCTL OPEN command opens a key-sequenced file for access by NonStop NET/MASTER MS. The following code segment uses the INTCMD verb to execute the UDBCTL OPEN command from an NCL process: … SAY "Opening "&filename INTCMD "UDBCTL OPEN="&filename" ID="&id INTREAD … Opening the File for Access by NCL The FILE OPEN verb opens a key-sequenced file for access by NCL.
Working With Files Working With Single Key-Sequenced Files Adding a Record to a Mapped Key-Sequenced File The following code segment adds records to a mapped key-sequenced file: … ASSIGN MDO=&rec. MAP=$NCL /* Allows you to enter 4 fields for 4 records */ DO &rno = 1 TO 4 DO &fno = 1 TO 4 SAY Enter record &rno field &fno CMDLINE "-GO ID="&SYS.NCLID _ PAUSE VARS=&field&fno PARSE=NO END /*&fno do*/ ASSIGN MDO=&rec. MAP=$NCL FROM VARS=&field* SAY "Adding record "&rno" to "&filename FILE ADD KEY=&rno MDO=&rec.
Working With Files Working With Single Key-Sequenced Files Adding a Record to a Delimited Key-Sequenced File The following code segment adds records to a delimited key-sequenced file: … /* Allows you to enter 4 fields for 4 records */ DO &rno = 1 TO 4 DO &fno = 1 TO 4 SAY Enter record &rno field &fno CMDLINE "-GO ID="&SYS.NCLID _ PAUSE VARS=&field&fno PARSE=NO END /*&fno do*/ SAY "Adding record "&rno" to "&filename FILE ADD KEY=&rno VARS=&field* SAY "Key is "&SYS.FILE.
Working With Files Working With Single Key-Sequenced Files 2. Retrieve the record that exactly matches the current key by using a FILE GET verb that either specifies OPT=KEX or omits the OPT operand, for example: FILE GET OPT=KEX ARGS The second option requires one FILE GET verb to retrieve a record. The FILE GET verb both sets the current record key and retrieves the record, for example: FILE GET KEY=ABCDEF ARGS Figure 12-14 illustrates exact retrieval. Figure 12-14.
Working With Files Working With Single Key-Sequenced Files Generic Retrieval Generic retrieval assumes that the value of the current key is a partial key. A partial key is a truncated version of a full key. In a partial key, only some of the leading characters are supplied. Retrieval by partial key is normally used when the entire key is not known or when many records have keys that are similar.
Working With Files Working With Single Key-Sequenced Files Table 12-7 lists the options you can use to specify the method of generic retrieval and set the retrieval direction to backward. Table 12-5. Generic Retrieval Options That Set Direction Backward Option Meaning KEL Retrieves a record with a record key generically equal to the specified key and sets retrieval direction backward.
Working With Files Working With Single Key-Sequenced Files The FILE SET verb sets the value of the partial key to JOHNSON. The first FILE GET verb finds the first record in the key-sequenced file that matches the partial key of JOHNSON. It sets the retrieval direction of subsequent FILE GET verbs to forward. Subsequent FILE GET verbs, which use the same OPT operand, sequentially retrieve all other records that match the partial key of JOHNSON.
Working With Files Working With Single Key-Sequenced Files Getting a Record From a Delimited Key-Sequenced File The following code segment gets all records from a delimited key-sequenced file, beginning at the last record: … /* Get records and displays them on OCS window */ FILE GET OPT=BWD VARS=&field* DO WHILE &SYS.FILE.RC = 0 DO &fno = 1 TO &SYS.
Working With Files Working With Single Key-Sequenced Files Note When you obtain exclusive access to a record, you should ensure that the NCL process relinquishes the locked record as quickly as possible. It is not good practice to lock a record and then display a panel that waits for operator input since this may delay access to the record by other NCL processes.
Working With Files Working With Single Key-Sequenced Files Updating a Record in an Unmapped Key-Sequenced File The following code segment presents all records for update in an unmapped key-sequenced file (the value of the record key is obtained before executing this code segment): … /* Updates a record and adds to a file */ /* Key is obtained before presenting fields for update */ &answer = N SAY "Update record? (Y/N) Default=N" CMDLINE "-GO ID="&SYS.
Working With Files Working With Single Key-Sequenced Files Deleting a Record The FILE DEL verb deletes one or more records in key-sequenced file. You can delete records from mapped, unmapped, and delimited key-sequenced files. When you delete a record, you must specify the value of the record key, using the KEY operand, either before deleting the record, using the FILE SET verb, or when you delete the record, using the FILE DEL verb.
Working With Files Working With Single Key-Sequenced Files Generic Deletion Generic deletion assumes that the value of the current key (set by the KEY operand) is a partial key. A partial key is a truncated version of a full key. In a partial key only some of the leading characters are supplied. Deletion by partial key is normally used when you want to delete many records. Table 12-8 lists the options you can use to specify the method of generic deletion; Figure 12-17 illustrates generic deletion.
Working With Files Working With Single Key-Sequenced Files Deleting a Record in Mapped, Unmapped, and Delimited Files The way that data is organized in a file does not affect how you delete a record in the file. The following code segment deletes a record in a mapped, unmapped, or delimited file (the value of the record key is obtained before executing this code segment): … /* Deletes a record */ &answer = N SAY "Delete record? (Y/N) Default=N" CMDLINE "-GO ID="&SYS.
Working With Files Working With Single Key-Sequenced Files Example—Adding Records to a Key-Sequenced File The following NCL procedure adds four records to a delimited key-sequenced file. It obtains the records by pausing and waiting for input typed in at the OCS command input line. One line of input is regarded as one field in a record. Each record has four fields.
Working With Files Working With Single Key-Sequenced Files END open_file /* ==================== ADD RECORDS ==================== */ add_records: PROCEDURE SHARE &filename,&id /* Gets records from OCS command input line */ /* and adds to file. */ /* Allows you to enter 4 fields for 4 records */ DO &rno = 1 TO 4 DO &fno = 1 TO 4 SAY Enter record &rno field &fno CMDLINE "-GO ID="&SYS.
Working With Files Working With Single Key-Sequenced Files The following screen shows the results of executing the procedure: (12:13) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1206N $DATA2.JOHNNCLS.DKSUDB Creating file $DATA2.JOHNNCLS.DKSUDB Opening $DATA2.JOHNNCLS.
Working With Files Working With Single Key-Sequenced Files WHEN 16 THEN SAY "16 "&SYSMSG OTHERWISE SAY Unexpected error END /*select*/ END open_file /* ==================== GET RECORDS ==================== */ get_records: PROCEDURE SHARE &filename,&id /* Get records and displays them on OCS window */ FILE GET OPT=FWD VARS=&field* SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.KEY END /*do*/ WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Single Key-Sequenced Files Example—Updating Records in a Key-Sequenced File The following NCL procedure allows you to update records in a delimited key-sequenced file: zex1208n: PROCEDURE /* Reads records from and updates records in delimited */ /* key-sequenced UDB */ ON ERROR FLUSH IF &1 = "" THEN DO SAY "Must enter file name as first parameter" FLUSH END /*do*/ ELSE &filename = &1 &id = DKSUDB CALL open_file SHARE &filename,&id CALL get_records SHARE &filename,&id CALL cl
Working With Files Working With Single Key-Sequenced Files SAY "Field "&fno" is "&field&fno END /*do*/ CALL put_record SHARE &filename,&id,&key,&field* FILE GET KEY=&key UPDATE VARS=&field* SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.KEY END /*do*/ WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Single Key-Sequenced Files Example—Deleting Records in a Key-Sequenced File The following NCL procedure allows you to delete records in a delimited key-sequenced file: zex1209n: PROCEDURE /* Deletes records in a delimited key-sequenced UDB */ ON ERROR FLUSH IF &1 = "" THEN DO SAY "Must enter file name as first parameter" FLUSH END /*do*/ ELSE &filename = &1 &id = DKSUDB CALL open_file SHARE &filename,&id CALL get_records SHARE &filename,&id CALL close_file SHARE &filename,&i
Working With Files Working With Single Key-Sequenced Files END /*do*/ CALL delete_record SHARE &key FILE GET KEY=&key UPDATE VARS=&field* SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.KEY END /*do*/ WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Key Sequenced Files in a UDB Pair Working With Key- The structure of records in a key-sequenced file is briefly described earlier in this Sequenced Files in a section.
Working With Files Working With Key Sequenced Files in a UDB Pair Adding a Record Note The FILE ADD and FILE PUT verbs add a new record to a UDB pair. You can use either verb to add records to mapped, unmapped, and delimited key-sequenced files in a UDB pair. See the discussion on adding a record to an entry-sequenced file, earlier in this section, for information on how to construct a record before adding the record to a file.
Working With Files Working With Key Sequenced Files in a UDB Pair Getting a Record The FILE GET verb retrieves a record from a UDB pair. You can retrieve records from mapped, unmapped, and delimited key-sequenced files in a UDB pair. Note See the discussion on getting a record from an entry-sequenced file, earlier in this section, for information on sequential retrieval.
Working With Files Working With Key Sequenced Files in a UDB Pair Figure 12-19 shows sequential retrieval from both files in a UDB pair, beginning with the first record. Records are retrieved in order from 1 through 10. Figure 12-19. Sequential Retrieval From a UDB Pair FILE GET OPT=SEQ PATH=ANY MDO=&rec. File 1 File 2 1 A 1 B 2 E 4 I 7 L 8 X 9 2 B 3 C 5 G 6 H L 10 Z Legend 1 File 1 has read and write access. 2 File 2 has read-only access.
Working With Files Working With Key Sequenced Files in a UDB Pair When updating a record in a UDB pair, the FILE PUT verb operates as follows: If the record is in neither file, the record is added to the first file. This FILE PUT operation is the same as a FILE ADD operation (see Figure 12-18). If the record is in the first file but not the second file, the record in the first file is updated (see Figure 12-20). That is, a new record replaces the existing record in the first file.
Working With Files Working With Key Sequenced Files in a UDB Pair Figure 12-21. Updating a Record in a UDB Pair—Case 2 Before FILE PUT Verb. File 1 1 File 2 2 File 2 2 B C G FILE PUT KEY=B MDO=&rec. After FILE PUT Verb. File 1 1 B B Record B Added. Logically Updates Record B in File 2. C G Legend 1 File 1 has read and write access. 2 File 2 has read-only access.
Working With Files Working With Key Sequenced Files in a UDB Pair Figure 12-22. Updating a Record in a UDB Pair—Case 3 Before FILE PUT Verb. File 1 1 B File 2 2 File 2 2 B C G FILE PUT KEY=B MDO=&rec. After FILE PUT Verb. File 1 1 B B New Record B Replaces Existing Record B. C G Legend 1 File 1 has read and write access. 2 File 2 has read-only access. 049 Deleting a Record The FILE DEL verb deletes one or more records in a UDB pair.
Working With Files Working With Key Sequenced Files in a UDB Pair When deleting a record from a UDB pair, the FILE DEL verb operates as follows: If the record is in neither file, the FILE DEL operation fails. If the record is in the first file but not the second file, the record is deleted from the first file (see Figure 12-23). If the record is in the second file but not the first file, a delete-record is written to the first file (see Figure 12-24).
Working With Files Working With Key Sequenced Files in a UDB Pair Figure 12-24. Deleting a Record From a UDB Pair—Case 2 Before FILE DEL Verb. File 1 1 File 2 2 File 2 2 B C G FILE DEL KEY=B MDO=&rec. After FILE DEL Verb. File 1 1 B B Delete-Record B Added. Logically Deletes Record B in File 2. C G Legend 1 File 1 has read and write access. 2 File 2 has read-only access.
Working With Files Working With Key Sequenced Files in a UDB Pair Figure 12-25. Deleting a Record From a UDB Pair—Case 3 Before FILE DEL Verb. File 1 1 B File 2 2 File 2 2 B C G FILE DEL KEY=B MDO=&rec. After FILE DEL Verb. File 1 B 1 B Delete-Record B Replaces Existing C Record B. Logically Deletes Record B G in File 2. Legend 1 File 1 has read and write access. 2 File 2 has read-only access.
Working With Files Working With Key Sequenced Files in a UDB Pair Examples of Working With Key-Sequenced Files in a UDB Pair This subsection has six examples of NCL procedures that illustrate how to work with UDB pairs (record structure is mapped).
Working With Files Working With Key Sequenced Files in a UDB Pair create_file: PROCEDURE SHARE &custfile,&distfile /* Use FUP to create new key-sequenced files */ DO &i = 1 TO 2 IF &i = 1 THEN &filename = &custfile ELSE &filename = &distfile SAY "Creating file "&filename INTCMD "OPSYS SEND FUP CREATE "&filename", TYPE K,", "REC 512, KEYLEN 6" DO UNTIL &msgno = NNM0999 INTREAD VARS=(&msgno(7),*,&text) TYPE=ANY PARSE=NO IF POS("ERR 10",&text) > 0 THEN DO /* File exists, so flush NCL process */ SAY "Must ente
Working With Files Working With Key Sequenced Files in a UDB Pair CMDLINE "-GO ID="&SYS.NCLID _ PAUSE VARS=&key PARSE=NO SEGMENT=6 /* Construct and add record */ ASSIGN MDO=&rec. MAP=$NCL FROM VARS=&field* SAY "Adding record "&rno" with key "&key" to "&distfile FILE ADD KEY=&key MDO=&rec. SAY "Key is "&SYS.FILE.KEY SELECT &SYS.FILE.RC WHEN 0 THEN SAY "0 Record added" WHEN 4 THEN SAY "4 Record exists, not added" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Key Sequenced Files in a UDB Pair Example—Getting Records From the Read-Only File in a UDB Pair The following NCL procedure gets records from a key-sequenced file (before the file is opened as the read-only file in a UDB pair): zex1212n: PROCEDURE /* Reads records from a mapped key-sequenced UDB */ IF &1 = "" THEN DO SAY "Must enter a file name" EXIT END /*do*/ ELSE &distfile = &1 &id = UDBPAIR CALL open_file SHARE &distfile,&id CALL get_records SHARE &distfile,&id CALL clos
Working With Files Working With Key Sequenced Files in a UDB Pair SAY "Field "&fno" is "&field&fno END /*do*/ FILE GET OPT=SEQ MDO=&rec. SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.KEY END /*do*/ WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Key Sequenced Files in a UDB Pair INTCONT FILE OPEN ID=&id FORMAT=MAPPED MAP=$NCL SELECT &SYS.FILE.
Working With Files Working With Key Sequenced Files in a UDB Pair END close_file END zex1213n Example—Getting Records From a UDB Pair The following NCL procedure gets records from a UDB pair and displays them on an OCS window: zex1214n: PROCEDURE /* Reads records from a UDB pair */ IF &1 = "" OR &2 = "" THEN DO SAY "Must enter two file names" EXIT END /*do*/ ELSE &custfile = &1 &distfile = &2 &id = UDBPAIR CALL open_file SHARE &custfile,&distfile,&id CALL get_records SHARE &custfile,&distfile,&id CALL clo
Working With Files Working With Key Sequenced Files in a UDB Pair SAY Unexpected error END /*select*/ DO WHILE &SYS.FILE.RC = 0 ASSIGN VARS=&field* FROM MDO=&rec. DO &fno = 1 TO &SYS.VARCNT SAY "Field "&fno" is "&field&fno END /*do*/ FILE GET OPT=SEQ MDO=&rec. SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.KEY SAY "Path is "&SYS.FILE.PATH END /*do*/ WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Key Sequenced Files in a UDB Pair open_file: PROCEDURE SHARE &custfile,&distfile,&id /* Open UDB pair for NonStop NET/MASTER and NCL */ SAY "Opening "&custfile &distfile INTCMD "UDBCTL OPEN=("&custfile","&distfile") ID="&id INTREAD INTCONT FILE OPEN ID=&id FORMAT=MAPPED MAP=$NCL SELECT &SYS.FILE.
Working With Files Working With Key Sequenced Files in a UDB Pair END get_records /* ==================== PUT RECORDS ==================== */ put_record: PROCEDURE SHARE &id,&rno,&key,&field*,&rec. /* Update a record and add to UDB pair */ &answer = N SAY "Update record? (Y/N) Default=N" CMDLINE "-GO ID="&SYS.NCLID _N PAUSE VARS=&answer PARSE=NO SEGMENT=1 IF UPPER(&answer) = Y THEN DO DO &fno = 1 TO 4 SAY Enter record &rno field &fno with key &key CMDLINE "-GO ID="&SYS.
Working With Files Working With Key Sequenced Files in a UDB Pair &distfile = &2 &id = UDBPAIR CALL open_file SHARE &custfile,&distfile,&id CALL get_records SHARE &custfile,&distfile,&id CALL close_file SHARE &custfile,&distfile,&id EXIT /* ==================== OPEN FILE ==================== */ open_file: PROCEDURE SHARE &custfile,&distfile,&id /* Open UDB pair for NonStop NET/MASTER and NCL */ SAY "Opening "&custfile &distfile INTCMD "UDBCTL OPEN=("&custfile","&distfile") ID="&id INTREAD INTCONT FILE OPEN
Working With Files Working With Key Sequenced Files in a UDB Pair WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.ERROR WHEN 16 THEN SAY "16 "&SYSMSG OTHERWISE SAY Unexpected error END /*select*/ END /*do while*/ END get_records /* ================= DELETE RECORD ==================== */ delete_record: PROCEDURE SHARE &key /* Delete a record */ &answer = N SAY "Delete record? (Y/N) Default=N" CMDLINE "-GO ID="&SYS.
Working With Files Working With Edit Files Working With Edit The structure of records in an edit file is briefly described earlier in this section. This Files subsection describes how to work with edit files from an NCL process. It does so by presenting a series of code segments that you can use when you create your own NCL procedures.
Working With Files Working With Edit Files The following screen shows the result of executing the commands: (06:19) --------------------- OPERATOR CONTROL SERVICES ---------------------START OPSYS SEND FUP CREATE $DATA2.JOHNNCLS.EDITFILE, CODE 101 NNM1468 File Utility Program - T9074D30 - (15JUN91) System \SYS1 NNM1468 Copyright Tandem Computers Incorporated 1981, 1983, 1985-1991 NNM1456 CREATED - $DATA2.JOHNNCLS.EDITFILE NNM0999 *END* START OPSYS SEND FUP PURGE $DATA2.JOHNNCLS.EDITFILE ! NNM1456 $DATA2.
Working With Files Working With Edit Files The following screen shows the results of executing the commands: (07:05) ---------------------------------------------------------------------START OPSYS SEND EDIT GET $DATA2.JOHNNCLS.EDITFILE! NNM1468 TEXT EDITOR - T9601B30 - (08MAR87) NNM1456 CURRENT FILE IS $DATA2.JOHNNCLS.EDITFILE NNM0999 *END* START OPSYS EOF EDIT START OPSYS SEND FUP PURGE $DATA2.JOHNNCLS.EDITFILE ! NNM1456 $DATA2.JOHNNCLS.EDITFILE PURGED.
Working With Files Working With Edit Files Opening the File for Access by NCL It is most meaningful to open an edit file as an unmapped file since NCL has no control over the structure of the data—NCL can only read records from an edit file. The following code segment uses the FILE OPEN verb to open a previously created edit file for access by NCL: … FILE OPEN ID=&id FORMAT=UNMAPPED … Getting a Record The FILE GET verb retrieves a record from an edit file.
Working With Files Working With Edit Files Example of Working With an Edit File The following NCL procedure gets records from an edit file and displays them at an OCS window. Comments throughout the NCL procedure describe how it works. The edit file must exist before you attempt to read it. You must specify the file name as the first parameter when you execute the NCL procedure, for example: START ZEX1210N $DATA2.JOHNNCLS.
Working With Files Working With Edit Files WHEN 16 THEN SAY "16 "&SYSMSG OTHERWISE SAY Unexpected error END /*select*/ DO WHILE &SYS.FILE.RC = 0 SAY "Record is "&record /* Parse record into "fields" */ PARSE ARGS DATA=&record DO &fno = 1 TO &SYS.VARCNT SAY "Field "&fno" is "&&fno END /*do*/ FILE GET VARS=&record SELECT &SYS.FILE.RC WHEN 0 THEN DO SAY "0 Record retrieved" SAY "Key is "&SYS.FILE.KEY END /*do*/ WHEN 4 THEN SAY "4 Record not found or EOF" WHEN 8 THEN SAY "8 Error "&SYS.FILE.
Working With Files Working With Guardian Processes The following screen shows the results of executing the procedure to read itself (a TEDIT file): (12:47) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1210N $DATA2.ZNCLPGN.ZEX1210N Opening $DATA2.ZNCLPGN.
Working With Files Working With Guardian Processes (This page left intentionally blank) 12–108 106160 Tandem Computers Incorporated
13 Interaction With Users and Terminals There are many ways to interact with an NCL process and many ways that an NCL process can interact and communicate with users, terminals, and other NCL processes by using commands, core statements, and verbs. The command, core statement, or verb you select for interaction or communication depends on the task you need to perform.
Interaction With Users and Terminals Displaying Text on the OCS Command Input Line START verb, discussed in Section 16, “Environments and Command Processing,” which invokes an NCL procedure for asynchronous execution in the specified environment using the specified variables EMSREAD, LOGREAD, and MSGREAD verbs, discussed in Section 17, “Developing System-Level NCL Procedures,” which read a system-level message EMSALERT, EMSCONT, EMSSEND, LOGCONT, and MSGCONT verbs, discussed in Section 17, “Developing Syst
Interaction With Users and Terminals Displaying Text on the OCS Command Input Line The following example combines the CMDLINE and PAUSE verbs: zex1301n: PROCEDURE DO FOREVER DO 5 SAY "What a lovely day!" END CMDLINE "GO ID="&SYS.NCLID" Continue (Y/N) _Y" PAUSE VARS=(&var1, &var2, &var3) &var3 = SUBSTR( &var3, 1, 1 ) IF UPPER( &var3 ) = Y THEN ITERATE ELSE LEAVE END END zex1301n In this example, text is displayed by a SAY statement in a DO loop.
Interaction With Users and Terminals Delaying Execution for a Specified Time Delaying Execution for a Specified Time You can use the DELAY verb from an NCL process to suspend execution of the NCL process for a specified number of seconds. This can be useful if you want an NCL process to wait for another event to complete before continuing execution. The DELAY verb can pause execution up to 3 hours. If you specify DELAY=0, the DELAY verb is ignored.
Interaction With Users and Terminals Pausing for Operator Input The FLUSH command terminates execution of the NCL process. You can trap the run-time error raised by flushing the NCL process by using the ERROR or FLUSH_ERROR error handler. For more information, see Section 7, “Run-Time Error Handling.” Pausing for Operator You can use the PAUSE verb from an NCL process to suspend the execution of the Input NCL process and to display a message in the OCS message display area.
Interaction With Users and Terminals Writing a Message to a Terminal The following screen shows the results of executing the procedure twice: (06:50) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1303N Enter GO YES followed by a sentence, GO NO, or GO |NM1060 PROCEDURE ZEX1303N NCLID 15 PAUSED GO NO Whole string is: NO Word 1 is: NO Rest is: NNM1005 START ZEX1303N PROCESSING COMPLETE.
Interaction With Users and Terminals Writing a Message to a Terminal The following screen shows the results of executing the procedure: (10:46) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1304N JOHN SMITH Message sent from JOHN SMITH NNM1005 START ZEX1304N PROCESSING COMPLETE.
Interaction With Users and Terminals Defining and Using Action Function Keys Defining and Using This subsection discusses how to define and use action function keys. An action Action Function Keys function key is a function key defined using the ACT operand of the FK (or PF) command. An action function key is designed to pass the message next to which the cursor is positioned in an OCS window to an associated NCL procedure. Defining an action function key associates an NCL procedure with the key.
Interaction With Users and Terminals Defining and Using Action Function Keys The following example shows how to define and use an action function key. The SF1 function key is defined as an action function key in this example. The key is associated with an NCL procedure that, when the key is pressed, turns the roll-delete message next to which the cursor is positioned into a non-roll-delete (NRD) message with the OPER attribute.
Interaction With Users and Terminals Defining and Using Action Function Keys 2. Type the following command in the OCS command input line: FK SF1 ACT,ZEX1305N This command defines the SF1 function key as an action function key associated with the ZEX1305N NCL procedure.
Interaction With Users and Terminals Defining and Using Action Function Keys 3.
Interaction With Users and Terminals Defining and Using Action Function Keys 4. Type the following parameters in the OCS command input line: YES YELLOW BLINK These parameters are passed to the NCL procedure when the SF1 function key is pressed. When the WRITE verb is executed, these values determine the appearance of the message.
Interaction With Users and Terminals Defining and Using Action Function Keys 5.
Interaction With Users and Terminals Defining and Using Action Function Keys 7. Observe the results immediately after pressing the SF1 function key, as shown in the following screen: (13:33) --------------------- OPERATOR CONTROL SERVICES ---------------------FK SF1 ACT,ZEX1305N NNM1861 SF1 KEY SET SHOW PROCESS _ NNM0555 PROCESS OCCURRENCE - NMMS_STATIC2 $I006 STATIC NNM0999 *END* -> 13:33:25 NNM0555 PROCESS OCCURRENCE - NMMS_STATIC2 $I006 STATIC NNM1005 START ZEX1305N PROCESSING COMPLETE.
14 Working With Panels This section discusses the service provided by NonStop NET/MASTER Management Services (MS) called Panel Services. This service enables an NCL process to display panels: full-screen formatted displays that overlay an entire window. Panels have two purposes: to present information to users and to obtain information from users and NCL processes.
Working With Panels Panel Design Guidelines Table 14-2. Panel Control Statements Statement Description #ALIAS Specifies alternative names for fields in a panel description file. #ERR #FLD #INCLUDE Specifies what happens when internal panel validation finds an error. Specifies or modifies the attributes of a field character. Specifies a panel description file as a source of panel control statements. #NOTE #OPT #TRAILER Specifies a comment or comments.
Working With Panels Components in Panel Processing Note Terminal type affects how a panel looks when it is displayed. Factors affected include color, highlighting, intensity, and the number of rows and columns that can be displayed. It is recommended that you test your panels on different terminal types to ensure that the information is presented correctly.
Working With Panels Components in Panel Processing The following screen shows the results of executing the procedure: A tiny panel. Press any function key to proceed. While this panel is displayed, execution of the NCL process is suspended while it waits for user input. (The NCL process is suspended because the panel is synchronous.) When the user presses a function key, the PANEL verb completes its operation of displaying the panel.
Working With Panels The Structure of a Panel Description File The Structure of a A panel description file has two distinct parts: the control part and the display part. Panel Description File The control part and display part are clearly indicated in the following panel description file: #NOTE ZEX1402P <--+ #NOTE Displaying a menu.
Working With Panels The Structure of a Panel Description File A panel control statement can occur more than once. The sequence of panel control statements is not significant. The settings of later #ERR, #FLD, and #OPT panel control statements supplement the settings of earlier #ERR, #FLD, and #OPT panel control statements. A later #NOTE panel control statement does not supplement or override an earlier #NOTE panel statement (the #NOTE panel control statement is ignored during panel processing).
Working With Panels Writing Panel Description Files Writing Panel This subsection introduces you to writing panel description files by using Edit Description Files Services. It covers the following topics: Creating and modifying a panel description file Deleting a panel description file Panel description file size Performing a panel test For step-by-step instructions on performing the tasks described in this subsection, see Section 3, “An NCL Tutorial.
Working With Panels Writing Panel Description Files in the ZEX1412P panel description file, you can incorporate these three statements into the latter file. #NOTE #FLD [ #ERR #OPT ZEX1411P TYPE=INPUT ALARM=YES ALARM=YES INTENS=HIGH HLITE=USCORE EDIT=NUM RANGE=(1,5) INTENS=HIGH HLITE=USCORE COLOR=RED The ZEX1412P panel description file, listed next, provides the same display panel as the panel description file ZEX1402P, listed previously in the subsection, “The Structure of a Panel Description File.
Working With Panels Panel Description File Libraries Panel Description File Libraries System Panel Libraries and Files Panel description file libraries are subvolumes that store panel description files. A panel description file library may be a system panel library or a user panel library. This subsection explains the difference between system panel libraries and user panel libraries. A system panel library contains panel description files owned by a NonStop NET/MASTER MS system.
Working With Panels Panel Description File Libraries You can use the SHOW PARAM command to display the results of the PARAM PNLDISTSRC and PARAM PNLDISTCODE commands, as the following screen shows: (09:36) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW PARAM NNM0605 CONFIG FILE=$DATA4.ZNNM.CONFIG NNM0605 PROCESSCHAR=Z NNM0605 INIT=INIT NNM0605 READY=READY NNM0605 SWGUID=YES NNM0605 DID=SYS1 NNM0605 NCLDISTSRC=$DATA4.ZNNMNDS NNM0605 NCLCUSTSRC=$DATA4.
Working With Panels Panel Description File Libraries You can use the SHOW PARAM command to display the results of the PARAM PNLCUSTSRC command, as the following screen shows: (09:36) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW PARAM NNM0605 CONFIG FILE=$DATA4.ZNNM.CONFIG NNM0605 PROCESSCHAR=Z NNM0605 INIT=INIT NNM0605 READY=READY NNM0605 SWGUID=YES NNM0605 DID=SYS1 NNM0605 NCLDISTSRC=$DATA4.ZNNMNDS NNM0605 NCLCUSTSRC=$DATA4.ZNNMNCS NNM0605 NCLDISTCODE=$DATA4.ZNNMNDO.
Working With Panels Panel Description File Libraries User Panel Libraries A user panel library contains panel description files that are owned by a particular user or group of users. All users may have access to the same library or each user may have access to a private library. The maximum number of private libraries is determined by the number of NonStop NET/MASTER MS users. The location of the panel description files belonging to a user is defined in the user ID definition record for that user.
Working With Panels Displaying Information About Panel Description Files Displaying Information As you create and modify panel description files, you may want to display About Panel information about the disk files and their contents. This subsection explains how you Description Files do so from Edit Services and OCS.
Working With Panels Displaying Information About Panel Description Files From OCS, use the SHOW FILEINFO command to display the names of panel description files, specifying the name of the panel library, as the following screen shows: (10:44) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW FILEINFO=$DATA.ZNCLPGP.
Working With Panels Factors Affecting Panel Description File Location From OCS, you can use the LIST command to display the contents of a panel description file, using the ID operand to specify the name of the panel library, as the following screen shows: (11:37) --------------------- OPERATOR CONTROL SERVICES ---------------------LIST ZUMSMN1P ID=$DATA9.ZNNMPDS NNM1018 #NOTE NNM1018 #NOTE NonStop NET/MASTER - T6581D30 - 22JUL91 NNM1018 #NOTE (C)1990, COPYRIGHT 1990 SOFTWARE DEVELOPMENTS INTERNATIONAL PTY.
Working With Panels Factors Affecting Panel Description File Location that are loaded by reference are displayed with a status of LOADED by the SHOW PANELS command; those that are explicitly preloaded are displayed with a status of PRELOADED.) Keeping the active panel queue allows panel description files that may be used frequently over short periods of time to have a high probability of retention in memory between display requests.
Working With Panels Factors Affecting Panel Description File Location The Default Search Path The default search path that an NCL process uses to locate a panel description file affects the panel description file it finds when there is more than one of the same name. The order of the search path that an NCL process uses to search for any panel description file is: 1. User panel library, the name of which is defined in your user ID definition record. 2.
Working With Panels Factors Affecting Panel Description File Location How to Customize the Panel Search Path The NCLCOMP command allows you to individually compile panel description files and place them in an object file of your choice. The file must have the same subvolume as the distributed panel object file; this file can then be included in a customized panel search path.
Working With Panels Factors Affecting Panel Description File Location Preloading and Unloading A preloaded panel description file is a panel description file that has been loaded into memory by using the SYSPARMS PPRELOAD command. The purpose of explicitly preloading a panel description file is to avoid the time and resources associated with searching for it when it is referenced by an NCL process.
Working With Panels Factors Affecting Panel Description File Location Note Test Mode Reducing the value of the SYSPARMS MAXPANEL from its current value to 1 clears all but one of the panel description files loaded by reference from the queue. (The most recent panel description file loaded by reference remains on the queue.) Test mode is the name given to a setting that you control while you are writing and testing NCL procedures and panel description files.
Working With Panels Factors Affecting Panel Description File Location Interaction When Test Mode Is On If test mode is on when an NCL process attempts to display a panel description file, NonStop NET/MASTER MS tries to locate the panel description file on disk. NonStop NET/MASTER MS uses the default or customized search path to search for it, beginning with the user panel library. If NonStop NET/MASTER MS finds a match, the NCL process uses the panel description file to display the panel.
Working With Panels Displaying Information About Panels Displaying Information About Panels You can use the SHOW PANELS command to display information about panel description files in the active panel queue.
Working With Panels Displaying Information About Panels 2. Type the ZEX1402P panel description file displayed earlier in this section (without the indicators down the right side of the screen) in your user panel library. 3. Execute the ZEX1402N NCL procedure from the OCS command input line, using the following START command: START ZEX1402N 4.
Working With Panels Displaying Information About Panels 5. Enter a value from 1 through 5, press a function key to remove the panel from display, and then observe the results of executing the NCL procedure, as shown in the following screen: (14:37) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1402N Value entered is 5 Key pressed is ENTER NNM1005 START ZEX1402N PROCESSING COMPLETE.
Working With Panels Displaying Information About Panels 2. Type the following panel description file in your user panel library and call it ZEX1403P: |---|----|----|----|----|----|----|----|----|----|----|----|----|----|----|----| #NOTE ZEX1403P #NOTE Hello world #FLD ? COLOR=BLUE INTENS=LOW HLITE=BLINK <-- 1 <-- 2 <-- 3 <-- 4 <-- 5 <-- 6 <-- 7 <-- 8 <-- 9 <-- 10 <-- 11 %Hello world from ?&SYS.USER.ID %at ?&SYS.DATE.
Working With Panels Displaying Information About Panels 4.
Working With Panels Including Comments in a Panel Description File 5. Press either the F3 or F4 function key to remove the panel from display and observe the results of executing the NCL procedure, as shown in the following screen: (14:58) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1403N NNM1005 START ZEX1403N PROCESSING COMPLETE.
Working With Panels Defining Field Characters in a Panel Description File Defining Field The #FLD panel control statement defines the attributes of a field character. A field Characters in a Panel character is a nonalphanumeric character that precedes a field in the display part of a Description File panel description file, specifying how that field is displayed on a screen. A field is the smallest unit that can be defined in a panel description file and then displayed on a screen.
Working With Panels Defining Field Characters in a Panel Description File (The underscore is not used as a field character in the ZEX1402P panel description file.) You can add attributes to the standard, predefined field characters by using the #FLD panel control statement. Defining Alternative Standard Field Characters You can change the standard, predefined field characters using the #OPT panel control statement and the DEFAULT operand. This specifies alternative standard field characters.
Working With Panels Defining Field Characters in a Panel Description File If the first character on a line is not a valid field character, the plus sign, which displays an output field in low-intensity, is assumed. The implicit plus sign is overwritten with a blank character when the panel is displayed on the screen. Specifying Display Attributes When creating your own field characters, there are many operands you can use to specify display attributes.
Working With Panels Defining Field Characters in a Panel Description File There are SYSPARMS commands available for you to change the contents of these system variables. For example, to change the color for mandatory input fields to YELLOW, use the command: SYSPARMS SPINPHIC=YELLOW This command sets the system variable &SYS.PANEL.INPHIC to YELLOW. Refer to the NonStop NET/MASTER NCL Reference Manual for a complete description of these system variables.
Working With Panels Defining Field Characters in a Panel Description File Fixed output data typically include screen captions, field names, and the names of individual function keys. This does not change when a panel is displayed. Variable output data are data generated by Panel Services and NCL when the panel is being displayed. The data are extracted from NCL variables available in the NCL process when the panel is invoked. The data may be obtained from system variables or user variables.
Working With Panels Defining Field Characters in a Panel Description File 2. Type the following panel description file in your user panel library and call it ZEX1404P: #NOTE ZEX1404P #NOTE Obtaining name and age. #ERR INTENS=HIGH ALARM=YES #FLD @ TYPE=INPUT CAPS=NO HLITE=USCORE #FLD ^ TYPE=INPUT CAPS=NO EDIT=NUM #FLD < INTENS=HIGH JUST=LEFT PAD=#FLD ! INTENS=HIGH JUST=RIGHT #FLD { INTENS=HIGH JUST=RIGHT PAD=#FLD ? INTENS=LOW HLITE=BLINK #FLD $ INTENS=HIGH JUST=CENTRE CAPS=NO PAD=#OPT ALARM=YES <&sys.
Working With Panels Defining Field Characters in a Panel Description File 4. Observe the results, as shown in the following screen: 15:22:59------------------- Obtaining Name and Age -------------TUE 26-MAY-1992 Type name : John Smith Type age : 2001 (You can lie if you like) Check name: John Smith Check age : 2001 F3=Exit F4=Return The panel has two input fields. The first input field follows the Type name output field. The second input field follows the Type age output field.
Working With Panels Defining Field Characters in a Panel Description File 1. Type the following NCL procedure in your user procedure library and call it ZEX1413N: zex1413n: PROCEDURE /* Displays a panel that uses #ALIAS */ &a.very.long.alternate.name1=Overtype this field with data &a.very.long.alternate.name2=Do the same with this field &a.very.long.alternate.name3="And with this too" &a.very.long.alternate.
Working With Panels Defining Field Characters in a Panel Description File 6. After overwriting the first line as shown and pressing the ENTER key, the NCL procedure completes by displaying two fields, including the field that you entered, as follows: (13:40) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1413N The first field you typed was: HERE IS SOME DATA WHICH SHOULD BE RETURNED The last usage of name is: FURTHER DATA NNM1005 START ZEX1413N PROCESSING COMPLETE.
Working With Panels Defining Field Characters in a Panel Description File Specifying Field-Level Justification and Padding Field-level justification is performed on an entire field, including variables within the field, as delimited by defined field characters. Field justification analyzes the entire field, strips trailing blanks, and pads and justifies the remaining data. The #FLD operands controlling field-level justification are JUST and PAD.
Working With Panels Defining Field Characters in a Panel Description File 4. Observe the results, as shown in the following screen: Left justified null padding Right justified null padding Center justified null padding Left justified with padding[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[ ]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]Right justified with padding .........................Center justified with padding.........................
Working With Panels Defining Field Characters in a Panel Description File To observe the affect of variable-level justification and padding, follow these steps: 1. Type the following NCL procedure in your user procedure library and call it ZEX1406N: zex1406n: PROCEDURE /* Illustrates variable-level justification */ /* and padding */ &variable = DATA PANEL ZEX1406P END zex1406n 2.
Working With Panels Defining Field Characters in a Panel Description File 4. Observe the results, as shown in the following screen: DATA DATA DATA DATA[[[[[ ]]]]]DATA ..DATA... Left variable null Right variable null Center variable null Left variable pad[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[ Right variable pad]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]] Center variable pad..................................................
Working With Panels Defining Field Characters in a Panel Description File 2. Type the following panel description file in your user panel library and call it ZEX1407P: #NOTE ZEX1407P #NOTE Illustrates variable-level justification, #NOTE field-level justification and padding #FLD * VALIGN=LEFT JUST=LEFT #FLD $ VALIGN=RIGHT JUST=LEFT #FLD ^ VALIGN=CENTRE JUST=LEFT #FLD @ VALIGN=LEFT JUST=LEFT PAD=[ #FLD ? VALIGN=RIGHT JUST=LEFT PAD=] #FLD / VALIGN=CENTRE JUST=LEFT PAD=.
Working With Panels Defining Field Characters in a Panel Description File 4. Observe the results, as shown in the following screen: DATA Left variable left field null Right variable left field null Center variable left field null Left variable left field pad[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[[ Right variable left field pad]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]]] Center variable left field pad.......................................
Working With Panels Defining Field Characters in a Panel Description File The various ways output data can be manipulated and displayed are best described by a series of examples. Study the #FLD statements in the following panel description file and observe the results of displaying the panel on a screen: 1.
Working With Panels Defining Field Characters in a Panel Description File 2.
Working With Panels Defining Field Characters in a Panel Description File 4.
Working With Panels Defining Field Characters in a Panel Description File Finally, observe the post-panel values of the unchanged input variables: (07:19) --------------------- OPERATOR CONTROL SERVICES ---------------------Post-panel values are John Janet Jack Jill James Joyce 1A1 1A1 1A1 A1 A1 A1 1A1 1A1 1A1 NNM1005 START ZEX1408N PROCESSING COMPLETE.
Working With Panels Defining Field Characters in a Panel Description File Using hexadecimal mode, you can define any hexadecimal value in the range X’00’ through X’FF’ as a field character, excluding the following: X’00’ (null character) X’40’ (blank character) X’50’ (ampersand) To define a hexadecimal value, you must use the following syntax of the #FLD panel control statement: #FLD X’cc’ [ fld-operand ] cc specifies the hexadecimal value of the field character.
Working With Panels Defining Field Characters in a Panel Description File During this preliminary phase, field characters are ignored and substitution is used to change a panel line in any way you require. When preparsing is complete, the normal panel building process is performed. Substitution uses the occurrence of the ampersand (&) to indicate the start of a variable string. These strings can be resolved to reflect the content of the variable, as set by an NCL process before it executes the PANEL verb.
Working With Panels Defining Field Characters in a Panel Description File Preparsing Syntax The general syntax of a preparse specification is: #OPT PREPARSE=( character, { D | S } ) character specifies a single alternative substitution character to be used during the preparse phase. It cannot be an ampersand. The alternative substitution character is used as the substitution character for the preparse phase.
Working With Panels Defining Field Characters in a Panel Description File Example of Dynamic Preparsing Dynamic preparsing is best described by a series of examples. Study the #FLD statements in the following panel description file and observe the results of displaying the panel on a screen. 1.
Working With Panels Defining Field Characters in a Panel Description File 4.
Working With Panels Defining Field Characters in a Panel Description File 2.
Working With Panels Defining Trailer Lines in a Panel Defining Trailer Lines in a Panel You can create a panel description file that enables you to position text at the bottom of a panel regardless of the size of the screen on which the panel is displayed. This is useful for positioning function key prompts that are conventionally placed at the bottom of a screen.
Working With Panels Defining Trailer Lines in a Panel 4. Observe the results as shown in the following screen: enter some data TEST PANEL FOR SHOWING TRAILER LINES ABRACADABRA this is the first trailer line in lower case and high intensity ------------here is a centered line padded with hyphens and in red------------this is the third trailer line the default color is white as in the first line THIS IS THE LAST TRAILER LINE IN UPPER CASE AND LOW INTENSITY 5.
Working With Panels Displaying a Panel Displaying a Panel Displaying a Synchronous Panel An NCL process displays a panel using the PANEL verb. There are two types of panels, each of which is displayed using the PANEL verb: synchronous and asynchronous. A synchronous panel is displayed by an NCL process using the PANEL verb with the TYPE=SYNC operand. Panel display is synchronous by default. A synchronous panel is a panel designed for direct interaction with a user at a terminal.
Working With Panels Displaying a Panel Updating a Panel Display When displaying a series of panels, if you want to achieve the visual effect of a smooth screen update, then you should use the same panel name in consecutive PANEL verbs. Otherwise, the user may notice a moment, between removing a panel from display and displaying the next panel, when a window is entirely blank.
Working With Panels Displaying a Panel 2. In the control part of the panel description file, use the #OPT statement and the CURSOR operand to specify the name of the variable from which to obtain the input field name: #OPT CURSOR=&ABC 3. Positioning the Cursor at a Certain Screen Location Display the panel using the PANEL verb. In this example, when the panel is displayed, the cursor is positioned on the F in the FIELD2 input field.
Working With Panels Displaying a Panel The Cursor Positioning Hierarchy Where you can position the cursor depends on the type of terminal on which the panel is being displayed. If the terminal is an IBM 3270 or compatible, you can position the cursor at any input field or at any screen location. If the terminal is a Tandem 6530 or compatible, you can position the cursor at any input (unprotected) field.
Working With Panels Displaying a Panel Displaying Panels on OCS Windows Any NCL process executing in the primary processing environment associated with an Operator Control Services (OCS) window can execute the PANEL verb in an attempt to take over the window and display a panel. OCS always grants this bid for the display area if it is operating in its usual rolling mode. It places the window in full-screen mode and queues any messages.
Working With Panels Displaying a Panel If the current owner of the window is executing with CONTROL SHAREW in effect, it automatically gives up its ownership to any other NCL process that executes a PANEL verb. The previous owner is then logically stacked behind the new owner. When the new owner ends or executes the PANELEND verb, the previous owner’s panel is redisplayed. The most common use of asynchronous NCL processes competing for a window is in an OCS environment.
Working With Panels Obtaining Input From a Panel Obtaining Input From a A panel that obtains input can pass back two types of values to an NCL process for Panel processing: the data entered into input field variables, and value of the key pressed by a user after entering data in an input field at a terminal. Obtaining Data in Input Field Variables Input field variables contain data received by the panel. Typically, this is data typed by a user at a keyboard.
Working With Panels Obtaining Input From a Panel Tandem 6530 or Compatible Terminal to IBM 3270 or Compatible Terminal Function Key Translation Table 14-4 lists the options of the CONTROL verb that allow you to control the translation of function key values from a Tandem 6530 or compatible terminal value to an IBM 3270 or compatible terminal equivalent. Table 14-4.
Working With Panels Obtaining Input From a Panel Table 14-5 lists the translations made for each unshifted function key on the Tandem 6530 or compatible terminal for each setting of CONTROL PFK3270, CONTROL PFKNATIVE, and CONTROL PFKGEN. Table 14-5.
Working With Panels Obtaining Input From a Panel Table 14-6 lists the translations made for each shifted function key (where the SHIFT key and the function key are pressed simultaneously) on the Tandem 6530 or compatible terminal for each setting of CONTROL PFK3270, CONTROL PFKNATIVE, and CONTROL PFKGEN. Table 14-6.
Working With Panels Obtaining Input From a Panel Table 14-7 lists the mapping made for each lower-row function key on an IBM 3270 or compatible terminal keyboard for each setting of CONTROL PFK3270, CONTROL PFKNATIVE, and CONTROL PFKGEN. (The settings of CONTROL PFKMAP and CONTROL NOPFKMAP determine whether upper-row function keys are mapped to lower-row function keys.) Table 14-7.
Working With Panels Obtaining Input From a Panel While using generic keys to perform generic operations is transparent to NCL processes that invoke full-screen panels, this may not always be desirable. You may want your NCL process to intercept all function keys and invoke alternative functions. Table 14-9 lists the options of the CONTROL verb that allow you to control the handling of function keys that perform a generic function. Table 14-9.
Working With Panels Obtaining Input From a Panel Table 14-10 lists the operands you can use to control the mapping of function keys on an IBM 3270 or compatible terminal. Table 14-10. Processing Program Function (PF) Keys Operand Description PFKMAP Enables mapping of upper-row function keys (PF13 through PF24) to lower-row function keys (PF01 through PF12). The system variable &SYS.INKEY contains a value from PF01 through PF12.
Working With Panels Obtaining Input From a Panel achieved by substituting variables in control statements, but this process becomes unwieldy. Panel Services facilities are provided to simplify the notification of errors.
Working With Panels Obtaining Input From a Panel RANGE=( start, end ), to specify that the entered data must be numeric and in a certain range. Internal validation error processing depends on how the CONTROL [NO]PANELRC option is set. If CONTROL NOPANELRC is set, automatic internal validation occurs. If CONTROL PANELRC is set, advanced internal validation may be used.
Working With Panels Obtaining Input From a Panel If you use CONTROL PANELRC, the NCL process retrieves control if internal validation detects that a required field has been omitted. The name of the field in error is supplied in a variable called &SYS.PANEL.FLD and the text of the error message registered by internal validation is supplied in the &SYSMSG variable. If an NCL process uses advanced internal validation, you must write it so that it can handle all possible return codes from the PANEL verb.
Working With Panels Obtaining Input From a Panel In the case of asynchronous panels, if the FMTINPUT operand is not specified in the panel description file, the input fields will only be reset the first time the panel is displayed or when the panel is redisplayed after the operator has signalled the end of input (by pressing ENTER or a defined function key).
Working With Panels Obtaining Input From a Panel Handling Input From Asynchronous Panels When an NCL process executes an asynchronous panel, the PANEL verb does not wait for input from the terminal. Another mechanism is needed to tell the NCL process when input is received. The mechanism used is the INTREAD verb and the dependent request queue of the NCL process that issued the PANEL verb. The mechanism works in the following way.
Working With Panels Obtaining Input From a Panel If an INPUT or CHANGE event occurs, it is recommended that the NCL process issue another PANEL statement to place the input into the asynchronous panel. This statement must specify the name of the panel being displayed when the INTREAD verb was issued. When the PANEL verb completes it operation, the result of the operation is placed in the &SYS.RETCODE system variable.
Working With Panels System Variables Set by the PANEL Verb System Variables Set by the PANEL Verb The system variables that are set as a result of displaying a panel are listed in Table 14-13. You can test these system variables from an NCL process after the PANEL verb has completed its operation. Table 14-13. System Variables Set by the PANEL Verb System Variable Contents of System Variable &SYS.CURS.
Working With Panels System Variables Set by the PANEL Verb 2. Internal validation handles all error processing automatically and redisplays the panel, if errors occur. 3. The NCL process determines whether the INWAIT interval has expired by testing &SYS.INKEY for a null value. 4. If a requested panel does not exist, or some other serious error occurs, the NCL process terminates with an error message unless you have set an error handler by using the PANEL_ERROR error handler.
Working With Panels System Variables Set by the PANEL Verb using the #OPT ERRFLD statement to display the error message unchanged and place the cursor on the field in error. In this last case, you can define the ERRFLD operand in the #OPT statement as ERRFLD=&SYS.PANEL.FLD to simplify processing. Using this return code is an ideal way of providing an escape mechanism (such as the F3 function key) even though the panel has been defined as having mandatory input field (using REQ=YES). Return Code 12.
Working With Panels Testing a Panel message by assigning a new message in the &SYSMSG variable, or redisplay the panel using the #OPT ERRFLD statement to display the error message unchanged and place the cursor on the field in error. In this last case, you can define the ERRFLD operand in the #OPT statement as ERRFLD=&SYS.PANEL.FLD to simplify processing.
Working With Panels Testing a Panel If no message is displayed, the panel test has been successful. In particular, this result indicates that the panel exists in the specified panel library, the panel was successfully displayed, one or more panel input fields have been modified, and internal validation has not detected any errors.
Working With Panels Panel Skipping and Navigation in the Panel Hierarchy The panel description file exists in the panel library but is not accessible. The following messages indicate this error: UNABLE TO ACCESS PANEL panel PANEL panel, ERROR G-error-number If these error messages are displayed, use the SHOW FILEINFO command from OCS to check the security attributes of the file or examine the accompanying Guardian error number. (The error number is the value in the variable &SYSMSG.
Working With Panels Panel Skipping and Navigation in the Panel Hierarchy NCL supports navigation at two different levels. The default implementation handles most navigation functions as part of the PANEL verb. However, you can explicitly handle navigation in your NCL procedures if you wish. Primary Menus and General Menus NonStop NET/MASTER MS supports two types of menus: primary menus and general menus. A primary menu is denoted by the display of a user ID and time on the right side of the screen.
Working With Panels Panel Skipping and Navigation in the Panel Hierarchy Explicit Handling of END and RETURN If CONTROL PFKSTD is set, the PANEL verb does not recognize the END and RETURN functions. The NCL process must check each function key that is pressed and take appropriate action. Note Setting CONTROL PFKSTD to explicitly handle the END and RETURN functions is not recommended.
Working With Panels Panel Skipping and Navigation in the Panel Hierarchy If the input data does not start with an equal sign and contains a period (.), the PANEL verb: Removes the leading substring, up to the first period Places the leading substring in the input variable Assigns the rest of the input data to the &SYS.PANEL.SKIP system variable Processes other input fields normally Note These actions apply only to PSKIP=GMENU.
Working With Panels Panel Skipping and Navigation in the Panel Hierarchy Explicit Panel Skip Handling If you wish, you can handle all aspects of panel skipping within an NCL procedure. To do so, you must set CONTROL PFKSTD to disable automatic panel skip handling. (This also stops the interception of the END and RETURN functions, as described earlier in this section.) When CONTROL PFKSTD is set, the PANEL verb can still perform skip-related actions. The NCL process can use the &SYS.PANEL.
Working With Panels Panel Skipping and Navigation in the Panel Hierarchy (This page left intentionally blank) 14–84 106160 Tandem Computers Incorporated
15 Working With Pathway Server Classes This section discusses how to work with existing Pathway server classes from an NCL process.
Working With Pathway Server Classes Pathway, NonStop NET/MASTER MS, and NCL For the complete syntax of verbs, refer to the NonStop NET/MASTER NCL Reference Manual. For the complete syntax of NonStop NET/MASTER MS commands, refer to the NonStop NET/MASTER MS Command Reference Manual. Note The Pathway transaction processing system is a group of related software tools and interfaces that enables you to develop, install, and manage online transaction processing applications.
Working With Pathway Server Classes Pathway, NonStop NET/MASTER MS, and NCL Figure 15-1.
Working With Pathway Server Classes Pathway, NonStop NET/MASTER MS, and NCL PATHMON and PATHCOM Figure 15-1 shows the Pathway Monitor (PATHMON) and PATHCOM processes. PATHMON is the central control process for a Pathway system. It is the first Pathway process started. PATHCOM is the command language interface used to communicate interactively with PATHMON to configure and control a Pathway system. After starting PATHMON, you can start PATHCOM and open communication with PATHMON.
Working With Pathway Server Classes Pathway, NonStop NET/MASTER MS, and NCL A PATHSEND requester includes two Guardian procedure calls that enable PATHSEND requesters to communicate with Pathway server classes: The SERVERCLASS_SEND_ procedure enables PATHSEND requesters to send data to and receive replies from a Pathway server class. The SERVERCLASS_SEND_INFO_ procedure enables PATHSEND requesters to get detailed information about the last SERVERCLASS_SEND_ operation.
Working With Pathway Server Classes Controlling Access to a Server Class by NonStop NET/MASTER MS If you wish, you can design the panels used by an NCL PATHSEND requester so that they look the same as the screen displays used by a requester written in another language. This means that a user can communicate with a server process by using screen displays with which they are already familiar. See Section 14, “Working With Panels,” for information on creating and using panel description files.
Working With Pathway Server Classes Controlling Access to a Server Class by NonStop NET/MASTER MS Assigning an Identifier to a Server Class When you make a server class available by using the PSNDCTL OPEN command, you must assign the server class an identifier before NCL can work with it. This is called a Pathway server class identifier. The server class identifier is the logical name used by NCL processes to access the server class, and provides a logical connection between NCL and a server class.
Working With Pathway Server Classes Controlling Access to a Server Class by NonStop NET/MASTER MS Specifying the Guardian User ID Your available Guardian user IDs (GUIDs) are assigned to you by User ID Management Services (UMS). You can determine your current GUID by using the PROFILE command. An NCL PATHSEND requester can operate under your current GUID or the GUID of NonStop NET/MASTER MS. This is controlled by the SWGUID operand of the PSNDCTL OPEN command.
Working With Pathway Server Classes Controlling Access to a Server Class by NonStop NET/MASTER MS Reassigning a Server Class Identifier to Another Server Class The ability to associate and disassociate a server class from an identifier provides you with considerable flexibility in handling server classes. In particular, it allows you to change the server classes that are referred to by an NCL process without modifying the NCL process.
Working With Pathway Server Classes Displaying Server Class Information Making a Server Class Unavailable to NonStop NET/MASTER MS You can use the PSNDCTL CLOSE command to make a server class unavailable for system-wide access. This command executes an implicit PSNDCTL STOP command for the associated identifier. Accordingly, the server class must not be in use. The following example makes the server class \SYS1.$PMON.SERVERCLASS1 unavailable for system-wide access: PSNDCTL CLOSE=\SYS1.$PMON.
Working With Pathway Server Classes Controlling Access to a Server Class by NCL Displaying Information About Server Class Users The SHOW PSNDUSER command displays information about the users and NCL processes currently using the server class, as the following screen shows: (15:33) --------------------- OPERATOR CONTROL SERVICES ---------------------SHOW PSNDUSER NNM0320 PSNDID USERID NCL-PROC NCLID TX AVG-RT AVG-MSG TIME-OPEN NNM0321 DYNAMIC NMTJN MAKE_SE* 002010 0000002 001.905 00000068 001130.
Working With Pathway Server Classes Controlling Access to a Server Class by NCL Table 15-2. System Variables Set by PSEND Verbs System Variable Contents of System Variable &SYS.PSEND.RC Contains a return code after each PSEND verb completes its operation. The value of the return code indicates the result of an operation. Contains (for some return codes) the Guardian file system error number, if applicable. Contains the current PATHSEND error number. This variable contains a value if the value of &SYS.
Working With Pathway Server Classes Making a Server Class Available for Access by NCL Making a Server Class The PSEND OPEN verb makes a server class available for processing by subsequent Available for Access PSEND verbs. You must make a server class available using the PSEND OPEN verb by NCL before any other PSEND verb can work with a server class.
Working With Pathway Server Classes Making a Server Class Available for Access by NCL When you make a server class available using PSEND OPEN, you have four available identifier options: After a server class is assigned a system-wide server class identifier by the PSNDCTL command, the NCL process uses one PSEND OPEN verb to make the server class available. The ID operand of the PSEND OPEN verb specifies the local server class identifier of the server class.
Working With Pathway Server Classes Making a Server Class Available for Access by NCL After a server class is assigned a system-wide server class identifier by the PSNDCTL command, the NCL process uses one PSEND OPEN verb to make the server class available. The PSEND OPEN verb uses both the PSNDID operand, which specifies the system-wide server class identifier of the server class, and the ID operand, which explicitly assigns a different local server class identifier to the server class.
Working With Pathway Server Classes Setting Server Class Characteristics Specifying Reply Message Structure Two types of messages flow between an NCL PATHSEND requester and a server process: request messages, which flow from the NCL PATHSEND requester to the server process; and reply messages, which flow from the server process to the NCL PATHSEND requester.
Working With Pathway Server Classes Making a Server Class Unavailable for Access by NCL In the following code segments, the PSEND SET verb switches from mapped to unmapped message structure: … PSEND OPEN ID=PSC_1 FORMAT=MAPPED MAP=REPMAP … PSEND SET FORMAT=UNMAPPED … In the following code segments, the PSEND SET verb switches from unmapped to mapped message structure: … PSEND OPEN ID=PSC_1 FORMAT=UNMAPPED … PSEND SET FORMAT=MAPPED MAP=REPMAP … In the following code segments, the PSEND SET verb switches to
Working With Pathway Server Classes Options for Specifying Message Structure Options for Specifying Request and reply messages can be either mapped or unmapped, but both types of Message Structure messages must have the same type of structure when communicating with a certain server class. That is, messages can be mapped and mapped, unmapped and unmapped, but not mapped and unmapped. This subsection describes in detail the options for specifying request and reply message structures.
Working With Pathway Server Classes Options for Specifying Message Structure 4. Use the PSEND SEND verb to send the request message. The following example sends a request message in the &REQMDO. MDO variable and receives a reply message in the REPMDO. MDO variable, which is mapped by the map REPMAP: PSEND SEND MDO=&REQMDO. TO MDO=&REPMDO. Mapped Reply Messages The structure of a mapped reply message is specified using the FORMAT=MAPPED and MAP operands in the PSEND OPEN or PSEND SET verb.
Working With Pathway Server Classes Options for Specifying Message Structure In both code segments, the name of the current map is REPMAP. After the PSEND SEND verb sends a request message, it receives a reply message in the REPMDO. MDO variable, which is mapped by the map REPMAP. Unmapped Message Structure An unmapped message is a message that is contained in ordinary variables. The DATA, ARGS, VARS, and RANGE operands of the PSEND SEND verb determine how the unmapped message is treated.
Working With Pathway Server Classes Options for Specifying Message Structure You can also obtain the request message in parameters, in a single variable, or as a constant expression. 2. Use the PSEND OPEN verb to make the required Pathway server class available for use by an NCL process. Use either the PSEND OPEN verb or the PSEND SET verb to specify that reply messages are unmapped.
Working With Pathway Server Classes Options for Specifying Message Structure The following PSEND SEND verbs use length variable specifications to split the following reply message: ABC XYZ 123 789 PSEND SEND VARS=&REQUEST* TO ARGS &1 = ABC XYZ 123 789 PSEND SEND VARS=&REQUEST* TO VARS=&A* &A1 = ABC XYZ 123 789 PSEND SEND VARS=&REQUEST* TO VARS=(&A*(1,2),&B*) RANGE=(3,4) &A1 = ABC XYZ 123 789 PSEND SEND VARS=&REQUEST* TO VARS=(&A(2),&B(2),&C(2),&D(2)) &A &B &C &D = = = = AB "C " XY "Z " PSEND SEND VARS=
Working With Pathway Server Classes Working With Server Classes Working With Server This subsection presents a step-by-step example that demonstrates how to Classes communicate with a Pathway server process from an NCL PATHSEND requester.
Working With Pathway Server Classes Working With Server Classes send_and_receive_message: PROCEDURE /* Sends a request message and receives a reply message */ ON PSEND_ERROR RESUME ASSIGN MDO=&req. MAP=ENTRY_MSG DO FOREVER PANEL ZEX1501P &reply = "" &req.pw_header.function_code = &fc &req.pw_header.reply_code = &r &req.message_number = &m PSEND SEND ID=ID1 MDO=&req. TO MDO=&rep. SELECT &SYS.PSEND.RC WHEN 0 THEN DO &status = "Message sent and received successfully" &reply = &rep.
Working With Pathway Server Classes Working With Server Classes 2. Type the following panel description file in your user panel library, calling it ZEX1501P: #NOTE ZEX1501P #NOTE Sending a message to and receiving a message from a #NOTE Pathway server class.
Working With Pathway Server Classes Working With Server Classes The values of the &SYS.PSEND.RC, &SYS.PSEND.ERROR, and &SYS.PSEND.PSERROR system variables indicate the success or failure of an operation performed by a PSEND verb. You can exit from the panel by pressing the F3 or F4 function key. 3. Type the following DDL source schema file in a convenient subvolume on your Tandem system, calling it ZEX15011: DEF ENTRY-MSG. 02 PW-HEADER. 04 REPLY-CODE 04 FUNCTION-CODE 02 MESSAGE-NUMBER END DEF ENTRY-REPLY.
Working With Pathway Server Classes Working With Server Classes 5. Type the following COBOL program in a convenient subvolume on your Tandem system, calling it ZEX15012: IDENTIFICATION DIVISION. PROGRAM-ID. EXAMPLE-SERVER. ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. TANDEM/16. OBJECT-COMPUTER. TANDEM/16. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT MESSAGE-IN, ASSIGN TO $RECEIVE FILE STATUS IS RECEIVE-FILE-STATUS. SELECT MESSAGE-OUT, ASSIGN TO $RECEIVE FILE STATUS IS RECEIVE-FILE-STATUS.
Working With Pathway Server Classes Working With Server Classes PROCEDURE DIVISION. BEGIN-COBOL-SERVER. OPEN INPUT MESSAGE-IN. OPEN OUTPUT MESSAGE-OUT SYNCDEPTH 1. PERFORM B-TRANS UNTIL CLOSE-FROM-REQUESTER. STOP RUN. B-TRANS. READ MESSAGE-IN, AT END STOP RUN. MOVE PW-HEADER OF MESSAGE-IN TO PW-HEADER OF MESSAGE-OUT. MOVE 0 TO ERROR-CODE OF WS. IF FUNCTION-CODE = "01" PERFORM READ-MESSAGE ELSE PERFORM FUNCTION-NOT-SUPPORTED.
Working With Pathway Server Classes Working With Server Classes 7. Define and add a Pathway SERVER object to your existing Pathway system.
Working With Pathway Server Classes Working With Server Classes 9. Observe the initial results, as shown in the following screen: EXAMPLE------------- NonStop NET/MASTER : PATHSEND Example -------------EXAMPLE +-----------------------------------+ | P A T H S E N D E x a m p l e | +-----------------------------------+ Status : Function code Reply code Message number : : : Reply : SYS.PSEND.RC : SYS.PSEND.ERROR : SYS.PSEND.
Working With Pathway Server Classes Working With Server Classes Function code 01 and message number 1 are entered. Accordingly, the reply message sent from server process to the NCL PATHSEND requester is “ONE ONE ONE ONE ONE.” 11. Experiment by entering different values in the Function code, Reply code, and Message number fields, and observe the different status messages, reply messages, and values in the various system variables.
Working With Pathway Server Classes Working With Server Classes (This 15–32 page left intentionally blank) 106160 Tandem Computers Incorporated
16 Environments and Command Processing This section discusses the relationships between NonStop NET/MASTER Management Services (MS) users, NonStop NET/MASTER MS environments, NonStop NET/MASTER MS commands, and NCL processes. The section begins by discussing the types of users that can use NonStop NET/MASTER MS and the types of environments in which users and NCL processes operate. The concept of environments is closely related to how NonStop NET/MASTER MS commands are executed from an NCL process.
Environments and Command Processing Table 16-2 summarizes the verbs and NonStop NET/MASTER MS command used to handle messages in an environment. Table 16-2. Verbs and NonStop NET/MASTER MS Command Used to Handle Messages in an Environment Verb or Command Description INTCLEAR verb Discards outstanding messages queued to a dependent processing environment. Propagates a message read using the INTREAD verb to the next higher processing environment and, optionally, changes its message text.
Environments and Command Processing Types of NonStop NET/MASTER MS Users Types of NonStop There are three types of users that can use a NonStop NET/MASTER MS system, each NET/MASTER MS of which is discussed in the following subsections: Users Real users Virtual users Remote users Real Users A real user is a person who logs on to a NonStop NET/MASTER MS system at a local terminal.
Environments and Command Processing Types of NonStop NET/MASTER MS Users The following command changes your own operator profile to allow the receipt of unsolicited messages: PROFILE UNSOL=YES The SHOW USERS and SHOW OCS commands display information about real users. Virtual Users Virtual users are NonStop NET/MASTER MS users that act the same as a real user and have the same attributes as real users operating in OCS, except that they do not have an associated terminal.
Environments and Command Processing Types of NonStop NET/MASTER MS Users Changing the Profile of a Virtual User The profile of a virtual user is changed using User ID Management Services (UMS). This changes the details in the user ID definition record of the user. If the details are changed, a real user can use the SUBMIT and SIGNON commands from OCS to implement the changes and refresh the profile of the virtual user.
Environments and Command Processing Types of NonStop NET/MASTER MS Users From the point of view of the local system, this type of user is a real user or virtual user who is allowed to enter OCS and so has an OCS profile. From the point of view of the remote system, this user is a type of virtual user (because the user does not have an associated terminal at the remote system). A typical example of a remote user is a network operator who controls many NonStop NET/MASTER MS systems from a local system.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments You can use the SHOW USERS and SHOW OCS commands to display information about remote users. Note You can filter messages from a remote system by specifying a MSGPROC NCL procedure at either the local system, the remote system, or both systems.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments NonStop NET/MASTER MS SHUTDOWN command. This command affects all users and requires an authority level of at least 4. NCL processes executed within a region affect only the user that owns the environment. This prevents one user from affecting or tampering with NCL processes in use by another user.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments NET/MASTER MS command (if you have sufficient authority) from the OCS command input line, including the EXEC and START commands. These commands execute NCL procedures from OCS. Figure 16-2 shows that the EXEC command queues NCL procedures for execution (because only one NCL process executed by EXEC can execute at a time in a processing environment).
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Figure 16-3. Environmental Hierarchy for a Real User Real User (With a Terminal) Region Top-Level Environment (NNM Primary Menu Window 1) Top-Level Environment (NNM Primary Menu Window 2) OCS Window 1 OCS Window 2 Primary Processing Environment Primary Processing Environment NCL NNM Dep. P.E. NCL Dep. P.E. NCL NNM NNM Dep. P.E. NNM NCL NCL NNM Dep. P.E. NNM Dep. P.E. NNM NCL Dep. P.E. NCL Dep. P.E.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Current Execution Environments A current execution environment is the environment in which a NonStop NET/MASTER MS command or NCL process is executing. It refers to the environment from the point of view of that command or NCL process.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Table 16-4 summarizes how the environment in which a NonStop NET/MASTER MS command is executed affects where the results of the command are sent. It also shows the owner of each type of current execution environment. Table 16-4.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments A top-level environment is the environment in which the NCL processes that display NonStop NET/MASTER MS menus operate. These are NCL processes that display the panels that show the NonStop NET/MASTER MS primary menu, the User ID Management Services (UMS) menus, the Edit Services selection list, the System Support Services menus, and so on.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Figure 16-4 shows the flow of NonStop NET/MASTER MS commands typed at the OCS command input line. Figure 16-4. Flow of Commands and Results From OCS OCS Window (Message Area) ==> NNM Command Results Primary Processing Environment Command Processing 014 Figure 16-5 shows the flow of NonStop NET/MASTER MS commands executed using the CMD core statement from an NCL process that is running in a primary processing environment.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Background Processing Environments If a NonStop NET/MASTER MS command or NCL process is executing in a background processing environment, the current execution environment is the background processing environment. A background processing environment is an environment that is owned and controlled by a virtual user.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Figure 16-6. Environmental Hierarchy for a Virtual User Virtual User (Does Not Have a Terminal) Background Processing Environment Primary Processing Environment NCL NNM Dep. P.E. NCL Dep. P.E. NCL NNM Dep. P.E. NNM NCL NNM Dep. P.E.
Environments and Command Processing Types of NonStop NET/MASTER MS Environments Dependent Processing Environments If a NonStop NET/MASTER MS command or NCL process is executing in a dependent processing environment, the current execution environment is the dependent processing environment. A dependent processing environment is an environment that is controlled and owned by an NCL process. Every NCL process can have a dependent processing environment associated with it.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process Entering NonStop NET/MASTER MS Commands From an NCL Process If you want to enter a NonStop NET/MASTER MS command from an NCL process, you must use either the CMD core statement or the INTCMD verb. The difference between CMD and INTCMD lies in the environment to which each sends the NonStop NET/MASTER MS command for execution.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process Figure 16-7 shows how the CMD core statement works in the current execution environment. Figure 16-7.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process Figure 16-8 shows how the CMD core statement works when it executes in the primary processing environment associated with an OCS window. Figure 16-8.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process The following screen shows the results of executing the procedure, passing the SHOW OCS command to it as a parameter: (11:03) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1601N SHOW OCS The command you have entered is SHOW OCS SHOW OCS NNM0398 -USERID- TERMINAL --------NAME-------- ------LOCATION------ STATUS NNM0399 NMTJN #3362826 JOHN NEW PUBLICATIONS ACTIVE NNM0999 *END* NNM10
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process Figure 16-9 shows how INTCMD executes commands in the dependent processing environment associated with an NCL process. It shows how INTREAD reads each message of the results and how INTCONT passes each message to the next higher processing environment. (In Figure 16-9 the next higher environment is the primary processing environment associated with an OCS window.) Figure 16-9.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process The following screen shows the results of executing the procedure: (11:11) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1602N SHOW OCS The command you have entered is SHOW OCS NNM1005 START ZEX1602N PROCESSING COMPLETE.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process The following screen shows the results of executing the procedure: (14:17) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1603N SHOW OCS The command you have entered is SHOW OCS NNM0398 -USERID- TERMINAL --------NAME-------- ------LOCATION------ STATUS NNM0399 NMTJN #5156654 John New PUBLICATIONS ACTIVE NNM0999 *END* NNM1005 START ZEX1603N PROCESSING COMPLETE.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process Figure 16-10 shows the result of an NCL process executing INTCMD START and INTCMD EXEC. It assumes that the top-level environment is a primary processing environment. It shows that the results of every NCL process flow to its owner. In particular, notice how the output from a command can flow to an OCS window. Figure 16-10.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process The following three NCL procedures show the flow of messages depicted in Figure 16-10. They illustrate how INTCMD passes a command to a dependent processing environment, and how INTREAD and INTCONT pass messages up the environmental hierarchy.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process The following screen shows the result of executing the first NCL procedure. The first NCL procedure then executes the second NCL procedure using INTCMD START. The second NCL procedure then executes the third NCL procedure using INTCMD EXEC. The third NCL procedure then executes the SHOW OCS command using INTCMD SHOW OCS.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process Figure 16-11. Combinations of CMD, INTCMD, START, and EXEC ==> START/EXEC OCS Window (Message Area) Primary Processing Environment Results NCL CMD NNM Results CMD NNM NCL CMD EXEC/ START Results CMD NNM NCL CMD EXEC/ START CMD EXEC/ START INTCMD START/EXEC Dependent Processing Environment Results NCL CMD NNM CMD EXEC/ START INTCMD START/EXEC Dep. Proc. Env.
Environments and Command Processing Entering NonStop NET/MASTER MS Commands From an NCL Process NonStop NET/MASTER MS Command Entry Restrictions When you enter a NonStop NET/MASTER MS command from an NCL procedure, you must enclose the command in quotes if it contains operators or special characters. The equal sign (=) is an example of a character that NCL uses as an operator. Refer to the NonStop NET/MASTER NCL Reference Manual for a complete list of operators and special characters.
Environments and Command Processing The Dependent Request and Response Queues Overriding Command Display and Logging When you enter a command from an NCL process by using the CMD core statement or the INTCMD verb, you can control command echoing and logging. You can stop a specific command from being echoed to the roll-delete message display area and from being logged in the NonStop NET/MASTER MS activity log by preceding the command with the suppression character (-).
Environments and Command Processing The Dependent Request and Response Queues Figure 16-12 shows that every dependent processing environment has a request and response queue. It also shows that the results of a NonStop NET/MASTER MS command are sent by default to the response queue. Figure 16-12 supplements the information presented earlier in this section in Figure 16-10. Figure 16-12.
Environments and Command Processing The Dependent Request and Response Queues The INTREAD, INTCONT, and INTCLEAR Verbs Three verbs are available to work with messages that arrive in the request and response queues: INTREAD INTCLEAR INTCONT Figure 16-13 shows the use of these verbs in a primary processing environment (although it could be any type of current execution environment). Figure 16-13.
Environments and Command Processing The Dependent Request and Response Queues When the INTREAD verb reads a message, it has the option of placing the text (but not the attributes of the text) into ordinary variables, using keywords such as ARGS, VARS, RANGE, SEGMENT, and PARSE. Refer to the discussion on verb syntax and variable access methods in the NonStop NET/MASTER NCL Reference Manual for more information about these keywords.
Environments and Command Processing The Dependent Request and Response Queues zex1608n: PROCEDURE /* Uses INTCMD to execute SHOW OCS */ INTCMD SHOW OCS DO UNTIL &msgno = NNM0999 INTREAD VARS=&msgno TYPE=RESP INTCONT END END zex1608n The following screen shows the result of executing the first NCL procedure. The first NCL procedure then executes the second NCL procedure using INTCMD START. The second NCL procedure then executes a command, SHOW OCS, using INTCMD SHOW OCS.
Environments and Command Processing The Dependent Request and Response Queues Passing on a Message From a Dependent Queue After reading a message using the INTREAD verb, you can use the INTCONT verb to pass the message to the next-higher-level environment. You can use the INTCONT verb to change some attributes of the message before the verb passes the message on. Using the INTCONT verb to change attributes updates fields in the MDO variable, &$INT., that contains the message.
Environments and Command Processing The Dependent Request and Response Queues zex1610n: PROCEDURE /* Uses INTCMD to execute SHOW OCS */ INTCMD SHOW OCS DELAY 5 DO &i = 1 TO &SYS.INT.RSP# INTREAD VARS=&msgno TYPE=RESP IF &msgno = "NNM0398" THEN INTCONT COLOR=BLUE HLITE=BLINK ELSE INTCONT END /*do*/ END zex1610n The following screen shows the result of executing the first NCL procedure. The first NCL procedure then executes the second NCL procedure using INTCMD START.
Environments and Command Processing The Dependent Request and Response Queues The &SYS.INTYPE system variable contains the name of the dependent queue on which a message has arrived. &SYS.INTYPE contains REQ if the message arrived on the request queue, or RESP if the message arrived on the response queue. If there is no message, &SYS.INTYPE contains a null value. Note Command processing and NCL process execution is asynchronous.
Environments and Command Processing The Dependent Request and Response Queues The following screen shows the results of executing the procedure: (09:26) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1611N STATUS NNM0608 SYSTEM STATUS AS AT 09:26:32 NNM0608 GUARDIAN VERSION: D30 NNM0608 SYSTEM STATE: RUNNING NNM0608 SYSTEM WAS INITIALISED ON MON 15-JUN-1992 AT 09:22:55 NNM1005 START ZEX1611N PROCESSING COMPLETE.
Environments and Command Processing The Dependent Request and Response Queues RETURN(&value) END get_value END zex1612n /* Return proc char /* End function */ */ This NCL procedure allows you to obtain the value of a single startup parameter. (Although you can display the value of single system parameters using the SHOW SYSPARMS command, you cannot display the value of a single startup parameter using the SHOW PARAM command.) Comments throughout the NCL procedure describe each step.
Environments and Command Processing Sending a Message to an NCL Process Using the INTQ Command Sending a Message to An OCS operator can use the NonStop NET/MASTER MS INTQ command from the an NCL Process, using OCS command input line to send a message to the dependent request or response the INTQ Command queue of a target NCL process. Note You should use the WRITE verb, rather than CMD INTQ or INTCMD INTQ, to send a message from another NCL process to another NCL process.
Environments and Command Processing Sending a Message to an NCL Process Using the INTQ Command Figure 16-14 shows how the INTQ command is used from the OCS command input line to send a message to an NCL process. The NCL process must issue INTREAD to read the message. (This figure assumes that SYSPARMS NCLXUSER=YES, since a message is sent from one region to another region that has a different user ID.) Figure 16-14.
Environments and Command Processing Sending a Message to an NCL Process Using the INTQ Command Example of the INTQ Command The following NCL procedure shows how to use INTQ from the OCS command input line to send a message to an NCL process. This NCL procedure waits for messages to arrive on its request queue. It reads each message, using INTREAD. It passes each message to the next higher level environment, using INTCONT. To see how this NCL procedure works, follow these steps: 1.
Environments and Command Processing Sending a Message to an NCL Process Using the INTQ Command 4. Observe the results of using the INTQ command from the OCS command input line to send a message to ZEX1613N: (12:50) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1613N NCL ID of ZEX1613N is 75 INTQ ID=75 DATA=This is a test message from OCS This is a test message from OCS FLUSH ID=75 NNM1022 FLUSH COMMAND ACCEPTED NNM1005 START ZEX1613N PROCESSING COMPLETE.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb Sending a Message Between NCL Processes, Using the WRITE Verb You can use the WRITE verb, by specifying an NCL ID, to send a message from one NCL process to the dependent request or response queue of a target NCL process. When you are sending messages between NCL processes, you should carefully consider how to send the message and how to read the message.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb The following WRITE verb does not specify the DATA operand and sends no text: WRITE NCLID=&nclid The result of reading a message depends on the syntax of the INTREAD verb that you use; in particular, whether you specify PARSE=YES or PARSE=NO.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb Specifying Ordinary Variables When Reading a Message The following two NCL procedures show how to use the WRITE verb to send text from one NCL process to a target NCL process that specifies ordinary variables when reading a message. To see how these NCL procedures work, follow these steps: 1.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb ASSIGN OPT=MDOELEMENTS ARGS FROM MDO=&mdo.&piece DO &i = 1 TO &SYS.VARCNT &y = &piecedot || &&i SAY &spaces || Element &&i is &mdo.&y CALL show_mdo( &nspaces + 2, &y ) SHARE &mdo. END ASSIGN OPT=MDOFIELDS ARGS FROM MDO=&mdo.&piece DO &i = 1 TO &SYS.VARCNT &y = &piecedot || &&i SAY &spaces || Field &&i is &mdo.&y CALL show_mdo( &nspaces + 2, &y ) SHARE &mdo.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb 5. Observe the results of using the WRITE verb from ZEX1617N to send text to ZEX1616N, as the following screen shows: (13:40) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1616N NCL ID of ZEX1616N is 265 START ZEX1617N &1 is a &2 is b &3 is c This message does not have a USERMDO &$INT.TEXT is a b c &$INT.USERMDO is &$INT.MAPNAME is Elements and fields in &MDO.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb SAY "&"&cvar" is "&&cvar END /*do*/ END /*do*/ WHEN $NCL THEN DO SAY "&MDO. = "&mdo. /* How many fields are there? */ ASSIGN OPT=MDOCOUNTS VARS=&mdocounts, FROM MDO=&mdo.datalist.data DO &cvar = 1 TO &mdocounts SAY "&"&cvar" is "&mdo.datalist.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb 5.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb The following WRITE verb sends ordinary variables, but does not specify the DATA operand and sends no text: … &1 = x &2 = y &3 = z WRITE NCLID=&nclid ARGS … The preceding code segment has the same result as the following code segment: … &1 = x &2 = y &3 = z ASSIGN MDO=&usermdo. MAP=$NCL FROM ARGS WRITE NCLID=&nclid MDO=&usermdo.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb The following table shows the result of using the WRITE verb to send ordinary variables by using the ARGS or VARS operand (with and without the DATA operand to send text), and the result of using an INTREAD verb that specifies PARSE=NO to read the message: WRITE Verb INTREAD Verb INTREAD PARSE=NO INTREAD PARSE=NO ARGS INTREAD PARSE=NO MDO=&mdo.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb After following the steps outlined earlier in this section to execute ZEX1616N, type ZEX1618N. The following screen shows the results of executing ZEX1618N: (13:42) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1616N NCL ID of ZEX1616N is 270 START ZEX1618N &1 is x &2 is y &3 is z This message has a USERMDO NNM1005 START ZEX1618N PROCESSING COMPLETE. NCLID 000271 &$INT.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb After following the steps outlined earlier in this section to install ZEX1620N as your active MSGPROC procedure, execute ZEX1622N to send a message to your OCS window.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb The following WRITE verb sends an enclosed MDO variable mapped by the map $NCL, but does not specify the DATA operand and sends no text: … &1 = x &2 = y &3 = z ASSIGN MDO=&usermdo. MAP=$NCL FROM ARGS WRITE NCLID=&nclid MDO=&usermdo. … The following WRITE verb sends an enclosed MDO variable mapped by the map $MSG, and also specifies the DATA operand to send text: … ASSIGN MDO=&usermdo. MAP=$MSG &usermdo.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb The following table shows the result of using the WRITE verb to send an enclosed MDO variable by using the MDO operand (with and without the DATA operand to send text), and the result of using an INTREAD verb that specifies PARSE=YES to read the message: WRITE Verb INTREAD Verb INTREAD PARSE=YES INTREAD PARSE=YES ARGS INTREAD PARSE=YES MDO=&mdo.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb The following table shows the result of using the WRITE verb to send an enclosed MDO variable by using the MDO operand (with and without the DATA operand to send text), and the result of using an INTREAD verb that specifies PARSE=NO to read the message: WRITE Verb INTREAD Verb WRITE NCLID=&nclid MDO=&usermdo. DATA=a b c WRITE NCLID=&nclid MDO=&usermdo. INTREAD PARSE=NO &$INT.TEXT=a b c &$INT.
Environments and Command Processing Sending a Message Between NCL Processes Using the WRITE Verb After following the steps outlined earlier in this section to execute ZEX1616N, type ZEX1619N. The following screen shows the results of executing ZEX1619N: (13:44) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1616N NCL ID of ZEX1616N is 272 START ZEX1619N &1 is a &2 is b &3 is c This message has a USERMDO &$INT.TEXT is a b c &$INT.USERMDO is . .x y z &$INT.
Environments and Command Processing Sending a Message to an NCL Process When it Is Started After following the steps outlined earlier in this section to install ZEX1620N as your active MSGPROC procedure, execute ZEX1623N to send a message to your OCS window.
Environments and Command Processing Sending a Message to an NCL Process When it Is Started Specifying the Environment The START verb can specify the environment in which the started NCL process executes. By default, the started NCL process executes in the current execution environment. Other environments in which the started NCL process can execute are the dependent processing environment associated with the invoking NCL process and the background processing environments in which virtual users execute.
Environments and Command Processing Sending a Message to an NCL Process When it Is Started To see how these NCL procedures work, follow these steps: 1. Type the first NCL procedure as shown, calling it ZEX1624N: zex1624n: PROCEDURE /* EMSPROC procedure for simple automation. */ /* An asynchronous NCL process is started by */ /* the START verb to handle specific Expand */ /* and SNAX/XF messages, which report line */ /* problems. */ DO FOREVER EMSREAD VARS=&msgid IF &$ems.
Environments and Command Processing Sending a Message to an NCL Process When it Is Started 4. Type the second NCL procedure as shown, calling it ZEX1625N: zex1625n: PROCEDURE /* Started by EMSPROC for simple automation. */ /* This asynchronous NCL process is started */ /* by the START verb to handle an Expand */ /* message, which reports line problems. */ CONTROL NOENDMSG &line = &$prm.spi.&($prm.spi.tandem.
Environments and Command Processing Sending a Message to an NCL Process When it Is Started 8. Observe the results of starting an NCL process to recover an Expand line after receiving an unsolicited message (EXP0045) reporting that an Expand line is not ready: (12:26) --------------------- OPERATOR CONTROL SERVICES ---------------------12:25:51 EXP0045 LDEV 0027 NET: LINE NOT READY, ERROR #066 12:25:54 E NCL PROCESS 109 STARTED FOR EVENT EXP0045 12:25:55 EXP-003 \SYS1.
Environments and Command Processing Executing Persistent NCL Processes Executing Persistent An NCL process is considered to be persistent when it has automatic restart capability. NCL Processes Using the RESTART Operand in the START Verb When an NCL procedure is started by using the START verb with RESTART=YES or RESTART=COND, and the START verb also specifies that the NCL process is started in a background processing environment, a backup process is assigned by NonStop NET/MASTER MS.
17 Developing System-Level NCL Procedures This section discusses how to develop system-level NCL procedures.
Developing System-Level NCL Procedures Overview of System-Level NCL Procedures Overview of SystemLevel NCL Procedures The EMSPROC NCL Procedure A system-level procedure is an NCL procedure that has access to distinct types of message flows within NonStop NET/MASTER MS, using certain verbs. There are two main system-level NCL procedures: EMSPROC and LOGPROC. In addition, MSGPROC NCL procedures are regarded as system-level procedures.
Developing System-Level NCL Procedures Overview of System-Level NCL Procedures You can use the SHOW SYSPARMS command to display the name of the current EMSPROC NCL procedure. You can use the STATUS command to determine whether EMSPROC is running.
Developing System-Level NCL Procedures Overview of System-Level NCL Procedures NonStop NET/MASTER MS system. Accordingly, LOGPROC can act as a central intelligence point to monitor events directed to the activity log. The procedure can observe and react to unusual or critical conditions, and provide a platform for automatic recovery action. Defining a LOGPROC NCL Procedure The SYSPARMS LOGPROC command is used to specify the name of a new LOGPROC NCL procedure and to flush an existing LOGPROC NCL procedure.
Developing System-Level NCL Procedures Overview of System-Level NCL Procedures Automatic Restart of EMSPROC and LOGPROC If a Guardian process that controls a background processing environment should fail, the Guardian process is recreated and EMSPROC and LOGPROC are restarted automatically by NonStop NET/MASTER MS. NCL processes started by EMSPROC or LOGPROC (or other NCL processes executing in the background processing environment) are not restarted automatically.
Developing System-Level NCL Procedures Overview of System-Level NCL Procedures You can use the PROFILE command to display the name of your current MSGPROC NCL procedure, as the following screen shows: (14:37) --------------------- OPERATOR CONTROL SERVICES ---------------------PROFILE MSGPROC=MSGPROCA NNM0357 PROFILE HAS CHANGED NNM0393 MSGPROC PROCESSING ACTIVATED PROFILE NNM0381 USERID: NMTMG TERMINAL-ID: #4970241 NNM0382 NCL PROCEDURE LIBRARY ID: $DATA.ZNCLPGN NNM0384 AUTOHOLD SETTING IS ON AUTO.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Message Profile Variables System-level NCL procedures are designed to perform tasks that are distinctly different from those of other NCL procedures. No other NCL procedures can intercept and process system-level message flows. Accordingly, system-level NCL procedures have specific development considerations.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures An NCL Process Can Obtain Information About a Message An NCL process can obtain information about the structure and attributes of a message, using the EMSREAD, INTREAD, LOGREAD, and MSGREAD verbs to read a message. (The INTREAD verb is discussed in Section 16, “Environments and Command Processing.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Section 10, “Working With Mapping Services,” for a detailed discussion of MDO variables. When one of these verbs reads a message, it has the option of placing the text (but not the attributes of the message) into ordinary variables using keywords such as ARGS, VARS, RANGE, SEGMENT, and PARSE.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Passing on a System-Level Message After reading a message using one of the EMSREAD, LOGREAD, or MSGREAD verbs, you can use the EMSCONT, LOGCONT, and MSGCONT verbs, respectively, to pass the message to its destination. The available destinations depends on the verb that reads the message.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures The following screen shows the results of executing the procedure: (13:59) --------------------- OPERATOR CONTROL SERVICES ---------------------PROFILE MSGPROC=ZEX1702N NNM0393 MSGPROC PROCESSING ACTIVATED NNM0357 PROFILE HAS CHANGED Full text is NNM0393 MSGPROC PROCESSING ACTIVATED Word 1 is NNM0393 Word 2 is MSGPROC Word 3 is PROCESSING Word 4 is ACTIVATED Full text is NNM0357 PROFILE HAS CHANGED Word 1 is N
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures The following screen shows the results of executing the procedure: (14:03) --------------------- OPERATOR CONTROL SERVICES ---------------------PROFILE MSGPROC=ZEX1703N Full text is NNM0393 MSGPROC PROCESSING ACTIVATED Word 1 is NNM0393 Word 2 is MSGPROC Word 3 is PROCESSING Word 4 is ACTIVATED Full text is NNM0357 PROFILE HAS CHANGED Word 1 is NNM0357 Word 2 is PROFILE Word 3 is HAS Word 4 is CHANGED ________
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Figure 17-1. A Closed Loop Begin Procedure Wait for Next Message Read Message When Available Closed Loop Process Message 043 As each message arrives, the NCL process should process the message. Processing involves analyzing the contents of the message and then either deleting the message (using the EMSDEL, LOGDEL, or MSGDEL verb) or passing the message on (using the EMSCONT, LOGCONT, or MSGCONT verb).
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Prevent the System-Level NCL Procedure From Terminating System-level NCL procedures should not be allowed to terminate once they begin execution. They should constantly monitor the flow of messages. If a system-level procedure terminates, a critical system-level message that you want to intercept and process may pass through to its destination undetected.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Using a Message Generator for Testing When you are testing a system-level procedure, you may need to check that it detects messages with specific attributes. To do so, you can use a message generator that sends a message with the attributes you are testing.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures The following screen shows the steps you should use: (15:15) --------------------- OPERATOR CONTROL SERVICES --------------------SYSPARMS EMSPROC=EPROC2 <-- Loads EMSPROC NNM0604 SYSPARMS EMSPROC=EPROC2 OPERAND ACCEPTED. 15:14:43 E EMSPROC starting SYSPARMS EMSPROC=FLUSH <-- Flushes EMSPROC NNM0604 SYSPARMS EMSPROC=FLUSH OPERAND ACCEPTED.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures Unloading LOGPROC From the Retain List. LOGPROC executes under the control of the virtual user LOGP. Loading LOGPROC using the SYSPARMS LOGPROC command loads it and places it on a list called the active list. If the value of the SYSPARMS NCLPRSHR system parameter is a number, then your NonStop NET/MASTER MS system also maintains a list called the retain list.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures See Section 8, “Executing NCL Procedures,” for more information on the active and retain lists. Loading and Flushing MSGPROC The PROFILE MSGPROC command can be used to either load or flush MSGPROC.
Developing System-Level NCL Procedures Development Considerations for System-Level NCL Procedures The following screen shows the steps you should use: (15:27) --------------------- OPERATOR CONTROL SERVICES --------------------PROFILE MSGPROC=MPROC2 <-- Loads MSGPROC NNM0393 MSGPROC PROCESSING ACTIVATED NNM0357 PROFILE HAS CHANGED MSGPROC starting PROFILE MSGPROC=FLUSH <-- Flushes MSGPROC NNM2202 MSGPROC FLUSHED NNM0357 PROFILE HAS CHANGED SHOW PRELOAD=MPROC2 <-- On retain list? NNM1050 NAME STATUS USERS R
Developing System-Level NCL Procedures Sending a Message to EMSPROC Sending a Message to You can use two verbs to send a message to EMSPROC for testing: EMSALERT and EMSPROC EMSSEND. The difference between these verbs lies in the path each uses to send the message and the resulting structure of the message when it arrives at EMSPROC.
Developing System-Level NCL Procedures Sending a Message to EMSPROC This table shows that the text, specified by the TEXT operand (ABC), is placed in &$EMS.SPI.TANDEM.ZEMS_TKN_TEXT, and also in &$EMS.TEXT prefixed by the subsystem identifier (NNM) and the event number (9999).
Developing System-Level NCL Procedures Sending a Message to EMSPROC The second NCL is a MSGPROC procedure called ZEX1707N. It is designed to trap messages that contain SPI tokens and have TEST in the message text, and to analyze and display their contents. The third NCL procedure is an NCL procedure called ZEX1708N. It uses the NCL EMSALERT verb to send a message directly to EMSPROC. To see how these NCL procedures work, follow these steps: 1.
Developing System-Level NCL Procedures Sending a Message to EMSPROC 4. Type the second NCL procedure as shown, calling it ZEX1707N: zex1707n: PROCEDURE /* MSGPROC procedure to analyze and filter messages with */ /* SPI tokens */ DO FOREVER /* Read message into a single variable */ MSGREAD VARS=&message PARSE=NO /* See if message text contains TEST */ &found = POS(TEST,&message) SELECT /* SPI tokens present and contains TEST */ WHEN &$msg.spi \= "" AND &found > 0 THEN DO SAY "&$MSG.TEXT is "&$msg.
Developing System-Level NCL Procedures Sending a Message to EMSPROC 7. Execute the following commands to ensure that your OCS profile allows you to receive EMS and unsolicited messages: PROFILE EMS=YES UNSOL=YES MONMSG=YES 8. Execute ZEX1708N from the OCS command input line by using the following command: START ZEX1708N 9.
Developing System-Level NCL Procedures Sending a Message to EMSPROC The following three NCL procedures show the results of sending a message using the EMSSEND verb. The first NCL procedure is an EMSPROC procedure called ZEX1706N, described earlier in this subsection. The second NCL is a MSGPROC procedure called ZEX1707N, described earlier in this subsection. The third NCL procedure is an NCL procedure called ZEX1709N.
Developing System-Level NCL Procedures Sending a Message to EMSPROC Finally, observe the results of installing ZEX1707N as your active MSGPROC procedure and executing ZEX1709N, as shown in the following two screens: Screen 1 of 2. (14:42) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1709N Sending a message to the EMS collector NNM1005 START ZEX1709N PROCESSING COMPLETE. NCLID 000025 14:42:28 NNM9999 TEST This is the &ABC.SPI.TANDEM.ZEMS_TKN_TEXT text &$MSG.
Developing System-Level NCL Procedures Identifying Messages From a Remote System Identifying Messages When EMSPROC at your local NonStop NET/MASTER MS system receives an event From a Remote message from a remote NonStop NET/MASTER MS system, you can easily identify System the node that generated the message by using the domain ID at the beginning of the message.
Developing System-Level NCL Procedures Tracing System-Level Messages Tracing System-Level NonStop NET/MASTER MS allows you to trace its operations by using a group of Messages TRACE commands to control tracing, and the SHOW TRACE command to display trace information. The TRACE commands provide the ability to perform two types of tracing: message tracing and internal event tracing. This subsection discusses message tracing in relation to system-level NCL procedures.
Developing System-Level NCL Procedures Tracing System-Level Messages Step 2. Specifying the Messages to Trace The second step in tracing system-level messages is to specify the messages to trace by using the TRACE trace-spec command. The TRACE trace-spec command makes changes to a set of trace parameter settings, which includes the trace file name and the messages to be traced.
Developing System-Level NCL Procedures Tracing System-Level Messages If you do not specify the name of a trace file, the trace file name is created from the default system name, the installation volume of NonStop NET/MASTER MS, the user ID of the user starting the trace, the process character of NonStop NET/MASTER MS, and the trace ID.
Developing System-Level NCL Procedures Tracing System-Level Messages Step 6. Examining the Trace File To examine trace records in a trace file created by NonStop NET/MASTER MS, you must use the PTrace utility distributed with NonStop NET/MASTER MS. If available, you can use the following command from the Operator Control Services (OCS) command input line to use this PTrace utility: OPSYS SEND PTRACE FROM $DATA9.NMTJN.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures After opening the trace file, you can use the PTrace utility to display records, as the following screen shows: (08:53) --------------------- OPERATOR CONTROL SERVICES ---------------------START OPSYS SEND PTRACE RECORD 1/5 NNM1456 12/16/92 07:59:43.541816 >000.000000 #1 MDS format NNM1456 Term: $ATP2.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures EMSPROC NCL Procedures The following EMSPROC NCL procedure allows all EMS messages to pass through unchanged: zex1710n: PROCEDURE /* Passes all messages unchanged */ SAY EMSPROC starting DO FOREVER EMSREAD END /*do*/ END zex1710n This NCL procedure does not delete messages and it does not change messages. It produces the same result as having no EMSPROC.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures The following EMSPROC NCL procedure filters and displays messages from the Expand and SNAX/CDF subsystems in distinctive colors; it also intercepts particular messages from those subsystems and displays those messages in distinctive ways. zex1712n: PROCEDURE /* EMSPROC to filter and display messages from various /* subsystems.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures LOGPROC NCL Procedures The following LOGPROC NCL procedure allows all log messages to pass through to the activity log: zex1713n: PROCEDURE /* Passes all messages unchanged */ SAY LOGPROC starting DO FOREVER LOGREAD END /*do*/ END zex1713n This NCL procedure does not delete messages and it does not change messages. It produces the same result as having no LOGPROC.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures &arg3 = "ABORT" ) OR , ( &arg5 = "START" OR , &arg5 = "STOP" OR , &arg5 = "ABORT" )) THEN DO &user = &$log.source.user &time = &$log.source.time &text = AT &time USER &user ATTEMPTED &1 &2 &3 &4 &5 &6 &7, &8 &9 FILE PUT ID=OLOG DATA=&text END /*if*/ END /*do forever*/ END zex1714n In addition, this NCL procedure logs all OPSYS commands used to start, stop, or abort objects in a separate file—an OPSYS activity log file.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures It does not delete messages and it does not change messages. It produces the same result as having no MSGPROC. Note As discussed earlier in this section, the MSGCONT verb is not required after the MSGREAD verb when a message is passed on with no changes.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures create_file: PROCEDURE /* Use FUP to try and create new entry-sequenced file. */ /* Set a large record length because MDO variables with*/ /* messages contain lots of attribute information. */ INTCMD "OPSYS SEND FUP CREATE $DATA2.JOHNNCLS.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures The following screen shows how to enable and disable logging; it executes the SHOW USERS command, which is sent to your own personal log file: (07:18) --------------------- OPERATOR CONTROL SERVICES ---------------------PROFILE MSGPROC=ZEX1717N NNM0393 MSGPROC PROCESSING ACTIVATED NNM0357 PROFILE HAS CHANGED MSGPROC starting START AAAAA Logging enabled NNM1001 NCL PROCEDURE AAAAA DOES NOT EXIST IN LIBRARY $DATA2.ZNCLPGN.
Developing System-Level NCL Procedures Examples of System-Level NCL Procedures The following screen shows the result of displaying the records in $DATA2.JOHNNCLS.MSGLOG: (07:19) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1718N UDBCTL OPEN=$DATA2.JOHNNCLS.MSGLOG ID=MSGLOG Text is NNM1001 NCL PROCEDURE AAAAA DOES NOT EXIST IN LIBRARY $DATA2.ZNCLPGN.
18 Advanced NCL Programming This section discusses some advanced NCL programming techniques.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database Note It is recommended that you use UMS rather than the SECCALL verbs for user ID management. (UMS uses the SECCALL verbs to update the database.) System Variables Set by SECCALL Verbs SECCALL verbs set the system variable &SYS.RETCODE to indicate the success or failure of an operation. You can test &SYS.RETCODE from an NCL process after a SECCALL verb has completed its operation.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database Table 18-2. SECCALL Verb Return Codes in &SYS.RETCODE (Page 2 of 2) Return Code SECCALL EXIT SECCALL GET SECCALL QUERY SECCALL UPDATE 0 * 4 * Record retrieved successfully. Error occurred, not retrieved, further information available in &SYSMSG. Information obtained successfully. Error occurred, not obtained, further information available in &SYSMSG. 8 12 16 20 24 28 * * * * * * Not used. Not used. Not used.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database Specifying at Least One Guardian User ID (GUID). Although not required syntactically by the SECCALL ADD verb, when you add an individual user ID definition record, you must also specify at least one Guardian user ID (GUID) for the user. At least one GUID is required by UMS. You must explicitly specify at least one GUID for the user in an MDO variable using an assignment statement before executing the SECCALL ADD verb.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database Example.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database The following screen shows the results of executing the procedure: (07:58) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1801N NNMABC MyPword USER MYNAME 100 22 ZHWKMMNN Y Y Y Creating an MDO variable with map $SEC Writing a record to the UMS database 0 Record added successfully 0 Record retrieved successfully NNM1005 START ZEX1801N PROCESSING COMPLETE.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database After creating a group user ID definition record, you can then create individual user ID definition records that belong to the group. You must explicitly assign the name of the group to an individual user ID definition record before executing the SECCALL ADD verb: The following example explicitly assigns the group CLASS1 to an individual user ID definition record: &abc.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database Changing a Record The SECCALL CHANGE verb changes passwords and a restricted set of personal details for existing user ID definition records in the UMS database. Password changes are either normal or forced. A normal password change changes your own password. This occurs when you simply decide to change your own password or when your password expires. A normal password change does not require UMS authority.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database The following screen shows the results of executing the procedure: (15:39) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1802N NNMABC MyPword NewPword 0 Password changed to NewPword NNM1005 START ZEX1802N PROCESSING COMPLETE.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database Changing Personal Details You can change the following personal details using the SECCALL CHANGE verb: user name, location, and phone number.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database The following screen shows the results of executing the procedure: (06:08) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1803N NNMABC NewPword MYNAME MYPLACE 1234567 Current user name is MYNAME Current location is Current phone is New user name is MYNAME New location is MYPLACE New phone is 1234567 NNM1005 START ZEX1803N PROCESSING COMPLETE.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database The following screen shows the results of executing the procedure: (06:16) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1804N NNMABC NewPword 0 Log on allowed NNM1005 START ZEX1804N PROCESSING COMPLETE.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database An alternative to using SECCALL GET to obtain your user ID information is using the SECCALL QUERY verb. This obtains user ID information about the current user from memory. This speeds up the access to user ID information by avoiding unnecessary disk access. The following example obtains user ID information about the current user from memory: SECCALL QUERY MDO=&MYDATA.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database SAY “RMS_ACCESS is "&ums.rms_access SAY "HLPM_ACCESS is "&ums.hlpm_access SAY "NCL_LIB is "&ums.ncl_lib SAY "NCL_OBJLIB is "&ums.ncl_objlib SAY "PANEL_LIB is "&ums.panel_lib SAY "USER_PROC is "&ums.user_proc SAY "USER_MENU is "&ums.user_menu SAY "AUTH_LEVEL is "&ums.auth_level SAY "SUSPEND_DT is "&ums.suspend_dt SAY "PW_EXPIRE is "&ums.pw_expire SAY "TIMEOUT is "&ums.timeout SAY "MULTI_LOGON is "&ums.
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database The following screen shows partial results of executing the procedure: (13:43) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1805N USERID is NMTJN GROUP_USERID is NORM_UDEFN is Y USERNAME is John New GUARDIAN_ID{2} is 100,21 GUARDIAN_ID{3} is 154,21 GUARDIAN_ID{4} is 0,0 GUARDIAN_ID{5} is 0,0 GUARDIAN_ID{6} is 0,0 GUARDIAN_ID{7} is 0,0 GUARDIAN_ID{8} is 0,0 GUARDIAN_ID{9} is 0,0 LOCATION is PUB
Advanced NCL Programming Accessing the User ID Management Services (UMS) Database The following screen shows the results of executing the procedure: (12:58) --------------------- OPERATOR CONTROL SERVICES ---------------------START ZEX1806N NMTJN USERNAME MYNAME User ID is NMTJN Element is USERNAME Value is MYNAME 0 NMTJN updated NNM1005 START ZEX1806N PROCESSING COMPLETE.
Advanced NCL Programming Altering NCL Process Execution Altering NCL Process NCL contains many core statements, verbs, and built-in functions to create powerful Execution logic capabilities. While each core statement, verb and built-in function has a specific effect when it is executed, you can modify or influence the mode of execution if you wish. All the processing options available to modify NCL execution characteristics are defined by a special verb—the CONTROL verb.
Advanced NCL Programming Synchronizing Access to Resources Synchronizing Access NCL applications that involve multiple users often need a mechanism for controlling to Resources access by different users or NCL processes to the same data or resource. This control is particularly important in NCL systems that use user databases (UDBs) or global vartables, which hold data that may be updated by some users while being read by others.
Advanced NCL Programming Synchronizing Access to Resources It is important to understand that it is not the data itself that is protected by the lock mechanism, only the resource that controls access to the data. In a UDB, for example, it is not a record that is locked—it is the resource that controls access to the data. If controlled access to an item of data is required, then all NCL processes that change that data must gain access to the lock before updating it.
Advanced NCL Programming Synchronizing Access to Resources Minor Names The minor name of a resource, if required, is a character string from 1 through 250 characters long which qualifies the resource’s primary name to identify a specific resource within a resource group. For example, the following primary name represents both a resource group and a specific resource: DOG The following resources represent specific resources within the DOG resource group: DOG.SPANIEL DOG.
Advanced NCL Programming Synchronizing Access to Resources An NCL process can also use the LOCK verb to test whether any other NCL process is holding a lock that it needs to access. Waiting for Access to a Resource If an NCL process issues a LOCK verb to request access to a resource lock, but the required access is not available immediately, the WAIT operand specifies whether the system returns control to the NCL process immediately or waits for the resource to become available.
Advanced NCL Programming Working With Vartables Working With A vartable is a memory resident table that contains entries with variable information. Vartables Vartables allow you to manipulate large quantities of variable information. The VARTABLE verbs establish vartable definitions and manipulate entries in a vartable. Table 18-4 summarizes the VARTABLE verbs. Table 18-4.
Advanced NCL Programming Working With Vartables Figure 18-1. Structure of a Vartable Definition Unique Identifier SCOPE AGE DATA DELOLD KEYFMT KEYLEN LIMIT USERCORR Entries Correlator Data 1 ••• Data n Unique Key Counter Correlator Data 1 ••• Data n ••• Counter ••• Unique Key 044 Defining a Vartable The VARTABLE ALLOC verb defines a vartable.
Advanced NCL Programming Working With Vartables Vartable Scope Vartable scope determines the visibility of the vartable to NCL processes and NonStop NET/MASTER MS users. It restricts the use of the vartable. Scope can be NCL process-wide, region-wide, or global. Scope is assigned using the SCOPE operand of the VARTABLE ALLOC verb. Process-wide scope is the default. This indicates that the table is visible only to the NCL process that creates it.
Advanced NCL Programming Working With Vartables For vartables defined with a value of LIMIT greater than zero (0), this operand indicates whether VARTABLE ADD and VARTABLE PUT can delete the oldest entry automatically when the table is full. Key Characteristics Keys uniquely identify entries. Every entry in a vartable has a key. There are two operands you can use with the VARTABLE ALLOC verb to specify the key characteristics—KEYFMT and KEYLEN.
Advanced NCL Programming Working With Vartables (This page left intentionally blank) 18–26 106160 Tandem Computers Incorporated
Glossary This glossary defines NonStop NET/MASTER and Tandem system terms and abbreviations used in this manual. %INCLUDE rule. An RMS message action rule that allows a message handler to use rules from more than one ruleset. %START rule. An RMS message action rule that instructs a message handler to perform user-defined initialization actions on startup. => prompt. Any prompt that ends with =>: for example, Command ===>, M=>, and Select Option ===>. absolute time.
Glossary attribute byte. The data that defines the display attributes of a field on a screen. The attribute byte is displayed as a blank on the screen. It is represented by a field character in a panel description file. authority level. A number assigned to users, NonStop NET/MASTER MS commands, and NonStop NET/MASTER MS operands that signifies the authority to execute a command or operand. Authority levels range from 0 (lowest) through 255 (highest). autohold.
Glossary BIU. See basic information unit. BK process. See background services process. blank concatenation operation. An operation that replaces multiple blanks between two terms in an expression by a single blank. block. A logical group of statements. Blocks are bounded by core statements such as PROCEDURE and END, FUNCTION and END, DO and END, and SELECT and END. BLOG. See Background Logger. BMON. See Background Monitor. Boolean.
Glossary COBOL85. The Tandem compiler and run-time support for the American National Standard Programming Language COBOL, X.3.23-1985. The code for most Pathway server processes is written using COBOL85. Command Entry facility. The NonStop NET/MASTER MS facility used as an alternative to OCS for entering commands. See also Operator Control Services. Command prompt. Command ===>. You enter commands at a Command prompt. Command Server Process.
Glossary communications network management (CNM). An IBM architecture that describes the structure of messages traveling to and from SNA devices. compilation. The process of creating object code from a source file of NCL statements. compilation error. An error in an NCL procedure detected during compilation (before execution). There are three types of compilation errors: from least to most severe these are warnings, errors, and fatal errors. See also error, fatal error, run-time error, and warning.
Glossary correlation key. An RMS key that restricts the use of a rule feature to messages with the same key. One example of a key is a text string containing variables. CPU weight. The relative availability of a CPU for the creation of dynamic processes. cultural indicator. An indicator that identifies the culture of command help information. culture.
Glossary DDL data dictionary. A database consisting of prenamed and predefined files created by the DDL compiler or Pathmaker. deadly embrace. A situation in which a resource required by one NCL process is indefinitely locked by another NCL process. debug. To locate and correct errors in an NCL process. decompilation. The process of creating NCL statements from object code. Decompilation occurs during the debugging of an NCL process, when using the DEBUG commands. dedicated terminal.
Glossary delimited UDB. A user database in which each field in a record is separated from the next field by hexadecimal ‘FF’ (called a field separator). dependent processing environment. A processing environment controlled and owned by an NCL process. The output from this environment goes to the NCL process. dependent queue. A queue owned by the NCL process that is controlling the associated dependent processing environment: either a request queue or a response queue. dependent request queue.
Glossary distribution procedure library. A library that contains the source code of NCL procedures distributed as part of a NonStop NET/MASTER MS installation or upgrade. DO group. A group of NCL statements enclosed by matching DO and END core statements that is executed only once. DO loop. A group of NCL statements enclosed by matching DO and END core statements that can be executed more than once. DOM ID. See delete operator message (DOM) ID. domain. A logical division within a network. domain ID.
Glossary EMS. See Event Management Service. EMS event collector. A Guardian process, part of the Tandem EMS subsystem, that collects and stores messages. The default EMS event collector is $0. EMS event distributor. An EMS process that distributes event messages from event logs to requesting management applications, to a collector on another node, or to printers, devices, or files. EMS message. A message generated internally by EMSPROC and identified by the letter E when displayed on an OCS window.
Glossary equate. A symbol defined to correspond to some text by the EQUATE command. The text is normally one or more NonStop NET/MASTER MS commands. There are two types of equates: local and global. error. A condition that causes the execution of a NonStop NET/MASTER MS command, the compilation of an NCL procedure, or the execution of an NCL process to fail (a run-time error). In NCL, a condition caused during compilation that would cause run-time errors if the NCL procedure were executed.
Glossary Expand. The Tandem network software that links together geographically distributed Tandem NonStop systems to create a network having the same reliability, capacity to preserve data integrity, and potential for modular expansion as a single system. explicit declaration. The definition of a procedure or function beginning with the PROCEDURE or FUNCTION core statement, respectively. explicit execution.
Glossary FK. See function key. fold. To convert a lowercase alphabetic character to its corresponding uppercase character. freeze. The act of inactivating RMS rules for a subject. When you freeze a subject, messages containing that subject cannot trigger any rules. full NRD message. A NRD message, held in the NRD message central queue, that must be deleted using its DOM ID. full-screen mode. A presentation mode in which a window consists entirely of a panel. function.
Glossary group. Any contiguous section of data within the fixed length data section of an element. group ID. The first part of a GUID consisting of a number from 1 through 255. group user ID. A user ID definition record, used as the default template for groups of individual users. Guardian user ID (GUID). The two-part Tandem ID, consisting of a group ID and a user ID, that defines a user to the Guardian environment. GUID. See Guardian user ID. header. The first part of a map or an element.
Glossary inclusive OR (OR). The Boolean operator that results in a value of 1 (TRUE) if one or both adjacent terms in an expression are true: otherwise the operator results in a value of 0 (FALSE). See also exclusive OR (XOR). indentation value. The number of columns used to indent the overrun lines of messages that are longer than the current width of an OCS window. INIT. The NCL procedure that is executed by the NonStop NET/MASTER MS control process (NCP) during system initialization. initial value.
Glossary internal trace point number. A number identifying a NonStop NET/MASTER MS internal event or other significant trace data. internal validation rules. Options specified in the #FLD panel control statement that determine how input is validated by Panel Services before it is passed to an NCL process. interpreter. The NonStop NET/MASTER MS entity that interprets an object and executes its opcodes. IS process. See inter-system services process. ISR. See Inter-System Routing. iterative. Repetitive.
Glossary line continuation character. The character used to continue an NCL statement over more than one line: in NCL, a comma (,). link definition. An INMC record, retained in global memory, that defines the characteristics, and registers the hierarchical relationship of its three components: a link definition record, a session definition record, and a unit definition record. link definition record.
Glossary manager. A process to which command messages for associated subjects are routed. In event messages, the managers make subjects of the same name unique. The ZEMS-TKN-MANAGER token contains the manager. map. A set of definitions used by Mapping Services that together describe the entire structure of some item of data. map definition record. A record in the NonStop NET/MASTER MS map file that describes the structure of a map. map file.
Glossary message ID. An ID that uniquely identifies a message. It is typically the first word of a message. message number. A number that uniquely identifies a message. It has two parts: the characters NNM and a unique number that can be used to refer to the message. message profile variable. A mapped data object variable that Mapping Services can understand using the map $MSG. message queue. A queue that holds roll-delete messages destined for an OCS window. message recognition element.
Glossary monitor-class message. A message that has the monitor-class attribute. Monitor-class messages are sent to monitor-class users. A monitor-class message is identified by the letter E, L, or M when it is displayed in an OCS window. monitor-class user. A user who is entitled to receive monitor-class messages. MS process. See multi-user services process. MSGPROC. A system-level NCL procedure that intercepts and processes messages destined for an OCS window. multi-user services (MS) process.
Glossary nested variable. A variable that begins with an ampersand and an opening parenthesis, and terminates with a closing parenthesis (&, (, and ), respectively). NET/MASTER. See SOLVE management services. Network Control Language (NCL). A structured, high-level, compiled language supplied with NonStop NET/MASTER MS and integrated with other NonStop NET/MASTER MS services. It is used to develop NCL procedures. Network Management Vector Transport (NMVT).
Glossary NRD message with the OPER attribute. A NRD message that is not held in the NRD message central queue, and must be deleted using NRD cursor deletion. When deleted, the message immediately disappears from the NRD message display area. null. No value. In NCL, assigning a variable a null value does not delete the variable name from memory. number. In NCL, a number is a symbol that begins with a digit (0 through 9) or a period and is in a context that permits it to be a number (rather than a string).
Glossary operand authority level. A number assigned to the operand of a NonStop NET/MASTER MS command. Authority levels range from 0 (lowest) through 255 (highest). A user whose authority level is equal to or greater than the operand authority level can execute the command using the operand. operating mode. The mode in which NonStop NET/MASTER MS is running, defined by the mix and presence or absence of application processes. See also advanced mode, basic mode, and extended basic mode.
Glossary panel library search path. The search order through the user panel library, customized panel library, and distribution panel library. panel object file search path. The search order through the panel object file(s) defined as part of the search path for panel description files. panel queue. A central queue, maintained by NonStop NET/MASTER MS, that holds panels currently in use. The maximum size of the queue is set by the SYSPARMS MAXPANEL command. panel skipping.
Glossary Pathway command terminal. A terminal at which a Pathway system manager enters PATHCOM commands to configure and control a Pathway system. Pathway server class identifier. A unique identifier that NonStop NET/MASTER MS assigns to a Pathway server class so that an NCL PATHSEND requester can communicate with the server class. Pathway system. The TCPs, servers, terminals, programs, and any subsystems associated with Pathway that run together under the control of one PATHMON process. pend-unload list.
Glossary primary menu. A menu denoted by the display of a user ID and time on the right side of the screen. NonStop NET/MASTER MS has more than one primary menu. primary name. The name given to an entire resource, used to control access to the resource by cooperating NCL processes. primary processing environment. A processing environment that is controlled and owned by an OCS window or a virtual user. The output from this environment goes to the OCS window or virtual user, respectively.
Glossary profile. A combination of details that determines what a user is allowed to do while using NonStop NET/MASTER MS. program attention (PA) key. A key on an IBM 3270 keyboard used to interrupt the execution of a program. Depending on the keyboard, there may be several PA keys. protected field. A field in a panel that cannot be updated by a user. PU. See physical unit. PUP. See Peripheral Utility Program. purge ID. An ID used to purge a timer command or NRD message. purge message.
Glossary relational operators. Operators that compare two terms in an expression and return either 1 if the comparison is TRUE, or 0 if the comparison is FALSE. relative time. A time value expressed in hours, minutes, and seconds representing an interval from the current time. Remote Operator Control (ROC).
Glossary response time monitor (RTM). Software in an IBM 3270 control unit that is responsible for measuring end-to-end application to terminal response time. restricted function selection. Selection of an option from the NonStop NET/MASTER MS primary menu by a user allowed to choose from a restricted set of options. retain list.
Glossary rule contents variable. An RMS variable that contains the value of certain rule definition elements. The variable name has the prefix $RMS. ruleset. A collection of RMS rules that defines responses to events such as message arrival and time conditions. The message handler uses the information in a ruleset to set up its execution environment and respond to incoming messages.
Glossary server class. A grouping of duplicate copies of a single server program, all of which execute the same object program. server process. A process that implements requests for an application and returns replies to the requester process. server program. A program in a Pathway system written using a language such as COBOL85, TAL, MUMPS, FORTRAN, BASIC, C, or Pascal. session definition record.
Glossary SOLVE management services. An integrated software product designed for network and system management on IBM 370, Fujitsu, and Nixdorf computer systems. See also NonStop NET/MASTER Management Services. source file. A disk file. source schema file. A file containing DDL statements, which define DDL objects. special character. In NCL, a lexical element that is a single character and acts as a delimiter in a statement. Its meaning depends on the current context. SPI.
Glossary stopped. The condition of an INMC link between NonStop NET/MASTER MS, SOLVE management services, and NetView systems that has been explicitly broken with the LINK STOP command. strict relational operator. A relational operator that compares two terms in an expression without adding blanks to or stripping blanks from either term. Both terms are treated as strings. strict test of equality. A test of equality by a strict relational operator. stripping.
Glossary synchronous. Two or more events occurring dependently. NCL procedures executed using the EXEC command execute serially and, therefore, synchronously. synchronous data link control (SDLC). The link-level protocol used for the transmission of SNA path information units (PIUs). synchronous panel. A panel displayed immediately by an NCL process that suspends processing while the panel waits for input. System Services Control Point (SSCP).
Glossary target label. In an NCL procedure, the label following a core statement for which the core statement searches. target NCL ID. The NCL identifier following a NonStop NET/MASTER MS command for which the command searches. target position. In an NCL procedure, a code position identified by a label. TCP. See terminal control process. term. The basic unit of an expression in NCL. There are five types of terms: symbols, quoted strings, variables, parenthesized expressions, and function references.
Glossary TPL. See trace parameter list. trace collector process. The NonStop NET/MASTER MS process that controls a running trace and the writing of records to a trace file. trace file. A file that collects and stores trace records. trace ID. The unique number that NonStop NET/MASTER MS assigns to a trace when the trace is started. trace parameter. A value in the trace parameter list specifying the events to trace. trace parameter list (TPL).
Glossary unit definition record. An INMC record, created by the UNIT DEFINE command, that names and establishes the characteristics of an INMC unit type. unit type. A type of logical path or connection; its manifestation depends on the session type. For X.25 session types, a unit is a virtual circuit (either SVC or PVC); for SNA, it is an LU; and for PTP, it is a file system OPEN. unloading. Removing an NCL procedure or panel description file from memory after it has been preloaded. unmapped UDB.
Glossary user ID. The unique identifier for a NonStop NET/MASTER MS user. user ID definition record. The record, created by UMS, that contains information about a particular user ID. User ID definition records are stored in the UMS database. user installation attributes. A set of characters that describes characteristics of the user ID definition that are meaningful to NonStop NET/MASTER MS. Using the SECCALL verb, NCL procedures can read and use the installation attributes for any purpose.
Glossary variable-level justification. In a panel, the process of stripping trailing blanks, padding, and justifying the data in a field after variable substitution. VARS list. A list of variable specifications beginning with the VARS keyword in a verb. vartable. A memory-resident table used for storing items of data that may change as the result of the execution of an NCL process. verb. Sometimes called a “verb statement,” an NCL statement that is not an intrinsic part of NCL.
Glossary (This page left intentionally blank) Glossary–40 106160 Tandem Computers Incorporated
Index 3270 or compatible terminal 7-25, 7-26, 14-61, 14-62 cursor positioning 14-58 END function key 14-65, 14-80, 14-83 function keys, mapping 14-61, 14-65, 14-66 program attention keys 14-61, 14-67 RETURN function key 14-65, 14-80, 14-83 SPLIT function key 14-65 SWAP function key 14-65 6530 or compatible terminal 7-25, 7-26 cursor positioning 14-58 END function key 14-65, 14-80, 14-83 function keys, translating 14-61, 14-62, 14-63, 14-64 RETURN function key 14-65, 14-80, 14-83 SPLIT function key 14-65 SWA
Index Advisory locks 2-18, 18-18 Alphabetic characters 2-2 Alternate keys 12-4, 12-24, 12-36, 12-41, 12-42 AND Boolean operator 2-2, 5-25 ARGS operand 2-14, 16-50, 16-59 Arithmetic errors 7-24 Arithmetic operators 2-21 ARITH_ERROR error handler 7-24 AS clause (DDL) 11-41 ASSIGN verb 2-14, 2-19 using with MDO variables 10-30/50 using with panels 14-70, 14-71 Assignment statement 2-10, 2-19 Asterisk 2-3 Asynchronous panels 14-70 coordinating input 14-73 displaying 14-55 event notification 14-72 receiving inp
Index Background Monitor (BMON) 16-4 environment 16-15 results from commands 16-12 submitting commands to 8-7 Background processing environments 16-7, 16-15 debugging 9-3, 9-17, 9-22, 9-28/29 Background System Process (BSYS) 16-4 environment 16-15 results from commands 16-12 submitting commands to 8-7 BASIC language 15-4 Basic operating mode, support for NCL 8-10, 14-16 Binary strings 4-5 Blank lines 4-2 Blanks, delimiting parameters with 6-22, 6-23 Blocks 2-4, 5-37, 7-16 BLOG See Background Logger BMON Se
Index C C language 11-28, 15-4 CALL core statement 2-8, 4-7, 6-36, 6-43, 6-46, 7-25, 13-1 NOSHARE keyword 6-31 parameters, passing with 6-20 SHARE keyword 6-31 sharing variables 6-31 Callee 2-19, 6-24 Caller 2-19, 6-24 CALLER keyword 6-35 CHANGE event, from asynchronous panels 14-73 Character mode 14-46 CIP See Conversational interface process CLEAR command 4-24 Closed windows 16-12 CMD core statement 2-10, 16-18, 16-24, 16-27 CMD operand, of CONTROL verb 16-30 CMDLINE verb 2-15, 13-2 CMDREPL operand, of S
Index Commands abbreviating 2-4 authority level 1-5 creating customized 1-5 customizing 1-5 entering from NCL 16-18 with CMD core statement 16-18 with INTCMD verb 16-21 entry restrictions from NCL 16-29 executing from NCL 1-5 replacing 1-6, 2-4, 8-4 suppressing echo 16-30 unrecognized, implicit execution 8-6 Comment delimiters 4-4 Comments 4-4 continuing across lines 4-4 delimiting 4-4 documenting online with 1-6 in decompiled source code 9-4 in panel description files 14-27 incorrect use of 9-4 nesting 4-
Index Compound variables 2-19 in DO loops 5-6 sharing 6-32 Concatenation operator See String operator Conditional clauses, in DO loops 5-12/17 CONSTANT clause (DDL) 11-41 Context 2-1 alphabetic characters 2-2 Boolean operators 2-2 data types 2-3 keywords 2-1 nonalphanumeric characters 2-3 numeric characters 2-3 reserved words 2-2 type conversion 2-3 Continuation character 4-1 Control part of panel description file 14-5 Control variable debugging 9-6 in DO loops 5-3, 5-6/11 CONTROL verb 2-18, 6-36, 18-17 Se
Index Cursor positioning 14-56 at input field 14-56 at screen location 14-57 hierarchy 14-58 Customized panel library 14-10, 14-17 Customized procedure library 4-16, 8-10 Customized procedures object file 4-17 Customizing commands, using NCL 1-5 Customizing NonStop NET/MASTER MS, using NCL 1-3/6 Cutting back 7-20 D Data component fields 10-23 fixed length 10-22 groups 10-22 of element 10-17 of MDO variable 10-17 variable length 10-22 Data Definition Language (DDL) 11-28, 11-29, 11-31, 11-32 for reply messa
Index Debug sessions default NCL ID 9-10 multiple 9-3, 9-30 resuming 9-25 single 9-3, 9-17/30 starting 9-3 multiple 9-3, 9-30 single 9-3, 9-17/30 stopping 9-7, 9-9, 9-17, 9-19, 9-20, 9-21, 9-25, 9-31, 9-59 switching 9-3, 9-31, 9-32 DEBUG SET command 9-3, 9-8, 9-32 DEBUG SOURCE command 9-4, 9-8, 9-9, 9-33, 9-34/43 BW operand 9-42 FW operand 9-39, 9-40 LOC operand 9-35, 9-36, 9-37, 9-40, 9-42, 9-43 NESTED operand 9-37 OFF operand 9-33, 9-58 ON operand 9-32, 9-33, 9-58 DEBUG START command 9-3, 9-8, 9-17/30 EN
Index Debugging (continued) guidelines 9-7/9 interactively 9-2 Log Browse 9-25 multiple NCL processes 9-3, 9-17 newly executed NCL processes 9-3, 9-17, 9-18, 9-20 online help 9-25 primary menus 9-22 primary processing environments 9-3, 9-17, 9-22/25 single NCL processes 9-3, 9-17 System Support Services 9-24 top-level environments 9-3, 9-17, 9-22/25 User ID Management Services (UMS) 9-24 User Services 9-24 windows 9-3, 9-28 Declaration explicit 6-9 implicit 6-11 variables 2-19 Decompilation 9-4 Decompiled
Index Distribution procedure library 4-15, 8-10 Division-by-zero errors 7-24 DO core statement 2-9, 4-7, 5-2 BY keyword 5-6, 5-9 FOR keyword 5-6, 5-11 FOREVER keyword 5-18, 5-19 label name space 4-11 scope 2-5, 7-16 TO keyword 5-6, 5-8 UNTIL keyword 5-12, 5-14, 5-15 WHILE keyword 5-12, 5-15 with IF core statement 5-26 with SELECT core statement 5-33 DO groups 5-2 DO loops controlling runaway 5-19 debugging 9-6 errors 7-25 executing forever 5-18 executing once 5-2 iterating 5-21 labels 5-21 leaving 5-23 nes
Index E E monitor prefix 16-12, 17-19 EDIT command 4-12 Edit files closing by NCL 12-42 by NonStop NET/MASTER MS 12-17 creating 12-8, 12-101 example NCL procedure for 12-105 getting records 12-104 opening by NCL 12-104 by NonStop NET/MASTER MS 12-103 record structure 12-5, 12-33 Edit Services 1-1, 4-12, 9-4, 14-7 browse option 4-24 debugging 9-24, 9-25 delete option 4-12, 14-7 displaying file names 4-22 test a panel 14-77 test compilation 4-13, 7-1, 9-7 using 3-4/17 EDIT text editor 12-5, 12-8 EDIT-PIC cla
Index EMSDEL verb 2-17, 17-11 EMSDIST command 17-2 EMSP See Event Management Service Process EMSPROC NCL procedure 1-2, 1-5, 2-17, 17-2 defining 17-2, 17-4 examples 11-19, 17-20, 17-24, 17-33/34 identifying messages from 17-19 obtaining status 17-3 preloading 17-15 restarting automatically 8-19, 17-5, 17-14 sending messages to 17-20 testing 17-15 tracing 17-29 unloading 17-15 verbs used by 17-3 EMSPROC operand, of SYSPARMS command 17-2, 17-4, 17-15 EMSREAD verb 2-17, 5-19, 10-30, 11-5, 13-2, 17-8 EMSSEND v
Index Entry-sequenced files adding records delimited 12-48 mapped 12-45 unmapped 12-47 closing by NCL 12-42 by NonStop NET/MASTER MS 12-17 creating 11-41, 12-8, 12-43 example NCL procedures for 12-52/55 getting records delimited 12-52 mapped 12-49 unmapped 12-50 opening by NCL 12-44 by NonStop NET/MASTER MS 12-44 delimited 12-44 mapped 12-44 unmapped 12-44 record structure 12-4, 12-5 delimited 12-35 mapped 12-30 unmapped 12-33 Enumerated MDO variables 10-25, 11-13, 11-14 Environments 16-7 background 16-7,
Index Error handlers debugging 9-5, 9-44 multiple 7-5 raising 7-15 releasing 7-20 replacing 7-17 scope 7-16 searching for 7-18 setting 7-14 setting breakpoints on 9-5, 9-44 sharing variables 7-20 system-defined 7-5, 7-23/28 See also individual system-defined error handlers user-defined 7-5 writing 7-4 Error messages 4-13, 7-2 Errors arithmetic 7-24 compilation 7-1 file 7-24 flush 7-24 labels 7-24 loadfail 7-25 looping 5-19, 7-25 panel 7-25, 7-26 PATHSEND 7-27 range 7-27 recovering from 7-11, 7-19 run-time
Index Event Management Service Process (EMSP) 16-4 EMSPROC NCL procedure controlling 17-2 unloading 17-15 environment 16-15 results from commands 16-12 submitting commands to 8-7 EVENTTD verb 2-15 EVERY command 8-6, 16-15 EXEC command 2-8, 6-43, 8-2, 13-1 execution by CMD core statement 16-24, 16-27 execution by INTCMD verb 16-24, 16-27 NCL process identifier 8-16 parameters, passing with 6-19, 6-20, 8-3 Executing commands, using NCL 1-5 Execution flow 5-1 Execution of DO groups repetitive 5-2 single 5-2 E
Index Explicit declaration 6-9 Explicit execution 8-1 with EXEC command 8-2 with START command 8-1 with START verb 16-59 Expressions 2-21 in DO loops 5-3 in IF core statement 5-25 in SELECT core statement 5-29 in statements 4-3 performance hints 5-25, 5-31 testing 5-25, 5-29, 5-31, 5-32 Extended BASIC language See BASIC language External functions 6-9 errors 7-25 External NCL procedures 6-9 errors 7-25 loading 9-7 EXTPARSE keyword, of PROCEDURE core statement 5-32, 6-22 F F16 function key See END function
Index Fields 10-2 in MDO variables 10-23 in panels 14-28 extent 14-29 input 14-31 output 14-31 in user-defined maps 11-35 obtaining names 10-45, 10-48 FILE ADD verb 10-31 entry-sequenced files 12-44 key-sequenced files 12-58, 12-80 FILE CLOSE verb 12-42 FILE DEL verb 12-68, 12-85 exact deletion 12-68 generic deletion 12-69 File errors 7-24 FILE GET verb 10-30 entry-sequenced files 12-48 key-sequenced files 12-60 exact retrieval 12-60 generic retrieval 12-62 FILE OPEN verb 12-22 FORMAT operand 12-29 ID oper
Index Files See also User databases closing by NCL 12-42 by NonStop NET/MASTER MS 12-17 controlling access to 12-10/17 creating 12-8 displaying physical information 12-18 displaying status information 12-19 displaying users of 12-20 edit 12-5 entry-sequenced 11-41, 12-4, 12-5 identifier specifying 12-22, 12-24 specifying current 12-38 key-sequenced 11-41, 12-4 opening by NCL 12-22/37 by NonStop NET/MASTER MS 12-10 panel description 14-3 comments in 14-27 control part 14-5 creating 14-7 display part 14-6 di
Index FILLER clause (DDL) 11-41 Filtering messages, using NCL 1-5 FINDRC operand, of CONTROL verb 7-25 FK command 13-8 using when debugging 9-11 FLDCTL operand, of CONTROL verb 14-70 FLUSH command 2-9, 7-24, 8-20, 16-17 FLUSH core statement 2-9 in error handler 7-7 Flush errors 7-24 FLUSH_ERROR error handler 7-24 FOLD keyword, of PROCEDURE core statement 5-32, 6-20 FOR keyword, of DO core statement 5-6, 5-11 FOREVER keyword, of DO core statement 5-18, 5-19 FORTRAN language 11-28, 15-4 FS-HOLD caption 14-59
Index Functions 6-1 See also Built-in functions callee 2-19, 6-24 caller 2-19, 6-24 calling 6-45 debugging 9-5, 9-44 declaring 6-9 displaying 6-6 external 6-6 getting started 3-22/27 internal 6-6 labels, searching for 6-48 name syntax 6-46, 6-47 nested 6-7 parameters, passing to 6-18 search order 6-46, 6-47 setting breakpoints on 9-5, 9-44 structure 6-6 terminating 6-13 G General menus 14-80 GENERIC operand 2-14 Getting started 3-4 Global variables 2-19, 2-20 in DO loops 5-6 sharing 6-32 GO command 8-20, 1
Index GOTO core statement 2-8, 4-7, 5-38 controlling runaway 5-19 label name space 4-11 label searching 5-39 LIMIT keyword 5-40 limiting label searching 5-40 MATCH keyword 5-42 matching labels 5-42 performance hints 5-39, 5-40, 5-42 scope 2-5 Group user ID definition record 18-6 Groups 10-2 in MDO variables 10-22 in user-defined maps 11-35 obtaining names 10-45 Guardian processes 12-6, 12-107 failure, effect on NCL 17-14 support for NCL 8-10, 14-16 Guardian user IDs, switching 2-18, 2-19 H Header of elemen
Index I IDS See Intelligent device support IF core statement 2-9, 5-25 performance hints 5-25 Implicit declaration, NCL procedures 6-11 Implicit execution 8-4 of commands 8-4 of MSGPROC NCL procedure 8-4 of unrecognized commands 8-6 Index integer See Integer index Indexed files See Key-sequenced files Indexed variables See Integer index Individual user ID definition records 18-3 INMC See Inter-NET/MASTER Connection INPUT event, from asynchronous panels 14-73 Input fields, in panels abbreviating long names
Index Interactive debugging 9-2 Internal validation errors 14-67, 14-68 Interpreter 8-8 INTQ command 13-1, 16-40 from OCS 16-42 MDO variables 16-40 INTREAD verb 2-17, 10-30, 11-5, 13-1, 14-55, 14-72, 14-73, 16-17, 16-32, 16-33 ISR See Inter-System Routing ITERATE core statement 2-9, 4-7, 5-21 label name space 4-11 label searching 5-24 Iterating, DO loops 5-21 J Justification, in panels input 14-42 output 14-36 field level 14-37 variable level 14-38, 14-40 K K command 4-24 Key field of element 10-14 of MDO
Index Key-sequenced files (continued) deleting records delimited 12-70 mapped 12-70 unmapped 12-70 example NCL procedures for 12-70/77 getting records delimited 12-65 mapped 12-64 unmapped 12-64 locking records 12-65 opening by NCL 12-58, 12-79 by NonStop NET/MASTER MS 12-58, 12-79 delimited 12-58 mapped 12-58 unmapped 12-58 record structure 12-4 delimited 12-35 mapped 12-30 unmapped 12-33 retrieval exact 12-60 generic 12-62 updating records delimited 12-67 mapped 12-66 unmapped 12-67 Keys See Alternate ke
Index L L monitor prefix 16-12, 17-19 Label errors 7-24 Labels 4-5 case 4-7 children 4-11 core statements using 4-7 errors 7-24 in decompiled source code 9-4 in DO loops 5-21 limiting search 5-40 matching 5-42 multiple 4-7 name spaces 4-11 naming functions 6-6 naming NCL procedures 6-6 nesting 4-11 parents 4-11 peers 4-11 performance hints 5-39, 5-40, 5-42 scope 2-5 searching functions 6-48 GOSUB core statement 5-39 GOTO core statement 5-39 ITERATE core statement 5-24 LEAVE core statement 5-24 NCL procedur
Index LIMIT keyword, of GOSUB and GOTO core statements 5-40 Line continuation character 4-1 Lines 4-1 renumbering 9-33 LINKMON processes 15-5 LIST command 4-24, 9-4, 14-15 Lists active 8-8, 8-10 pend-unload 8-9, 8-10 retain 8-9, 8-10 Loadfail errors 7-25 LOADFAIL_ERROR error handler 7-25 Location customized panel library 14-10 customized procedure library 4-16 customized procedures object file 4-17 distributed NCL object file 4-17 distributed panel object file 14-9 distributed procedures object file 4-16 d
Index LOGPROC NCL procedure 1-3, 1-5, 2-17, 17-3 examples 17-35 identifying messages from 17-19 obtaining status 17-4 preloading 17-16 restarting automatically 8-19, 17-5, 17-14 testing 17-16 tracing 17-29 unloading 17-17 verbs used by 17-4 LOGPROC operand, of SYSPARMS command 17-16 LOGREAD verb 2-17, 5-19, 10-30, 11-5, 13-2, 17-8 Looping errors 5-19, 7-25 LOOPING_ERROR error handler 5-8, 5-19, 7-25 M M mode indicator 16-8 M monitor prefix 16-12, 17-19 Managing NonStop NET/MASTER, using NCL 1-3/6 Map file
Index MATCH keyword, of GOSUB and GOTO core statements 5-42 MAXPANEL operand, of SYSPARMS command 14-16 MDMAINT program 11-32 MDO operand 2-14, 10-28 MDO variables 2-14, 2-19, 2-20, 10-2 accessing data 10-28 assigning data to 10-34 creating 10-30, 10-31 data component 10-17 debugging 9-5 deleting 10-33 element names, obtaining 10-47 elements 10-11 enclosed 10-17 enclosing 10-17 repeated 10-19 enclosed 16-44, 16-54 enclosing 16-44, 16-54 enumerated 10-25, 11-13, 11-14 field names, obtaining 10-48 fields 10-
Index Menus 14-80 errors 7-26 Message generator 3-29, 10-3, 11-19, 17-15, 17-20, 17-24 Message profile variables 10-5, 11-5, 11-11, 17-7 Message verbs 2-16 See also individual message verbs Messages changing display attributes 16-35 identifying source 17-19 intercepting 1-5 processing 1-5 performance hints 17-10, 17-14 recalling 4-14 reply 15-4, 15-6, 15-16, 15-18, 15-20 mapped 15-19 unmapped 15-21 request 15-4, 15-6, 15-16, 15-18, 15-20 mapped 15-18 unmapped 15-20 tracing system-level 17-28/31 Minor names
Index MSGPROC NCL procedure (continued) verbs used by 17-6 writing 3-28/34 MSGREAD verb 2-17, 5-19, 10-30, 11-5, 13-2, 17-8 MUMPS language 15-4 MUST BE clause (DDL) 11-41 N Name spaces, of labels 4-11 NCL 1-3 automation 1-4 communication 1-4 elements 2-6/21 features 2-1/6 file access 1-3 NonStop NET/MASTER MS services 1-1/2 panels 1-5 using 1-3/6 NCL ID See NCL process identifier NCL PATHSEND requesters 1-4, 15-2, 15-5, 15-6 See also PATHSEND requesters example 15-23 making server classes available from 15
Index NCL procedures 4-1, 6-1 callee 2-19, 6-24 caller 2-19, 6-24 calling 6-31, 6-43 creating 4-12 customizing the search path 8-11 debugging 9-5, 9-44 declaring 6-9, 6-11 deleting 4-12 displaying contents 4-24 displaying names 4-22, 6-6 displaying preloaded 8-18 distributed object file 4-17, 8-10 execution 8-1 and active list 8-8 and pend-unload list 8-9 and retain list 8-9 default search path 8-10 explicit 8-1 factors affecting 8-8 factors interacting 8-15 implicit 8-4 with EXEC command 8-2 with START co
Index NCL procedures (continued) return codes 6-1, 6-14 scope 4-1 search order 6-46 setting breakpoints on 9-5, 9-44 sharing 8-13 structure 4-1, 6-6 terminating 6-13 unloading 8-13 user specified object files 8-11 writing 4-12 NCL process identifier 2-8, 8-16 default 9-10 in &SYSMSG variable 16-60 when debugging 9-10 NCL processes 8-1 controlling 8-19 displaying current status of 8-17 displaying information about 8-17 execution continuing 9-6, 9-52, 13-5 delaying 13-4 pausing 13-5 resuming 9-6, 9-52, 9-53,
Index NCL processes (continued) performance hints (continued) test mode 8-15, 14-20 user ID information 18-13 variables 2-14, 2-19, 2-20, 6-33 vartables 18-24 persistent 8-19, 16-64 restarting automatically 8-19, 16-64, 17-5, 17-14 sending MDO variables between 16-40, 16-44/54 setting maximum number 8-21 terminating 8-19/20 trapping errors 7-1 NCLCHECK command 4-13, 7-1, 9-7, 17-14 NCLCUSTOBJ operand, of PARAM command 4-17 NCLCUSTSRC operand, of PARAM command 4-16 NCLDISTCODE operand, of PARAM command 4-17
Index NOFINDRC operand, of CONTROL verb 7-25 NOFLDCTL operand, of CONTROL verb 14-70 NOFOLD keyword, of PROCEDURE core statement 5-32, 6-20 Nonalphanumeric characters 2-3 NonStop NET/MASTER MS commands See Commands NonStop, and NCL 17-14 NOP core statement 2-10, 5-40 empty statements 4-12 with IF core statement 5-28 with SELECT core statement 5-29 NOPAKEYS operand, of CONTROL verb 14-67 NOPANELRC operand, of CONTROL verb 14-55, 14-69, 14-74 NOPFK operand 7-25 NOPFK operand, of CONTROL verb 7-25, 7-26, 14-6
Index OCCURS clause (DDL) 11-41 OCCURS DEPENDING ON clause (DDL) 11-41 OCS See Operator Control Services OCS verb 2-15 ON core statement 2-9, 7-4 SYSTEM keyword 7-6 Online documentation, using NCL 1-6 Opcodes 8-8 Open windows 16-12 Operands 2-13 Operating mode, support for NCL 8-10, 14-16 Operator Control Services (OCS) 1-1 displaying file names 4-23 displaying NCL procedure contents 4-24 displaying panel description file contents 14-15 displaying panels on 14-59 panel skipping 14-80 test compilation 4-13
Index P P mode indicator 16-8 Padding, in panels input 14-42 output 14-36 field level 14-37 variable level 14-38, 14-40 PAKEYS operand, of CONTROL verb 14-67 Panel bidding 14-59 Panel control statements 14-1, 14-5, 14-6 Panel description file libraries customized 14-10 distribution 14-9 system 14-9 user 14-12 Panel description files 1-5, 14-3 comments 14-27 control part 14-5 creating 14-7 debugging 9-3, 9-26 deleting 14-7 display part 14-6 displaying contents 14-13, 14-14, 14-15 displaying names 14-13, 14-
Index Panel libraries customized 14-17 default search path 14-17 distributed 14-17 object 14-17 user 14-17 Panel processing components 14-3 examples 14-22, 14-32, 14-37, 14-39, 14-40, 14-43, 14-50, 14-51 Panel queue See Active panel queue Panel skipping 14-79/80 PANEL verb 2-15, 7-25, 7-26, 13-1 TYPE operand asynchronous panels 14-55 synchronous panels 14-55 PANELEND verb 2-15, 14-55, 14-59 PANELRC operand, of CONTROL verb 14-55, 14-69, 14-70, 14-75, 14-77 Panels 1-5, 2-15, 14-4 debugging 9-3, 9-26 designi
Index Panels (continued) input 14-61 NCL PATHSEND requesters 15-5 presenting help 14-80 removing from display 14-55 return codes 14-55, 14-73, 14-74, 14-76 system-wide field attributes 14-30 PANEL_END error handler 7-25, 14-80 PANEL_ERROR error handler 7-26 PANEL_RETURN error handler 7-26, 14-80, 14-81 PANEL_SKIP_PMENU error handler 7-26 PARAM command NCLCUSTOBJ operand 4-17 NCLCUSTSRC operand 4-16 NCLDISTCODE operand 4-17 NCLDISTOBJ operand 4-16 NCLDISTSRC operand 4-15 NCLOBJLIB operand 4-19, 4-21 PNLCUST
Index PATHSEND errors 7-27 PATHSEND requesters 1-4, 15-2, 15-4 See also NCL PATHSEND requesters Pathway 15-2 PATHCOM command interpreter 15-4 PATHMON 15-4 PATHSEND requesters 1-4, 15-2, 15-4 reply messages 15-4, 15-16, 15-18, 15-20 mapped 15-19 unmapped 15-21 request messages 15-4, 15-16, 15-18, 15-20 mapped 15-18 unmapped 15-20 requester programs 15-4 requesters 1-4, 15-2, 15-4, 15-5 server classes 15-4 identifier 15-7 server processes 1-4, 15-2, 15-4 server programs 15-4 terminals 1-4, 15-4 Pathway serve
Index Persistence, and NCL 17-14 Persistent NCL 2-16, 16-64 PF command 13-8 PF keys See Function keys PF02 function key See SPLIT function key PF03 function key See END function key PF04 function key See RETURN function key PF09 function key See SWAP function key PF14 function key See SPLIT function key PF15 function key See END function key PF16 function key See RETURN function key PF21 function key See SWAP function key PFK3270 operand, of CONTROL verb 14-61, 14-62, 14-63, 14-64, 14-65, 14-66 PFKALL oper
Index Preloading EMSPROC NCL procedure 17-15 LOGPROC NCL procedure 17-16 MSGPROC NCL procedure 17-18 NCL procedures 8-12 panel description files 14-19 performance hints 8-12, 14-19 Preparsing 14-47 alternative substitution character 14-49 dynamic 14-48 static 14-48 Primary key 12-4, 12-24, 12-35, 12-36, 12-41, 12-42 Primary menus 14-80 debugging 9-22 errors 7-26 Primary names 18-19 Primary processing environments 16-7, 16-13 debugging 9-3, 9-17, 9-22/25 Procedure See NCL procedures PROCEDURE core statement
Index PROFILE command 16-3, 16-5, 16-6, 16-17 CMDKEEP operand 16-30 EMS operand 9-28, 16-3, 17-2 GUID operand 2-18 MONMSG operand 9-28, 16-3 MSG operand 9-28 MSGPROC operand 17-5 NCLTEST operand 8-14, 14-20 UNSOL operand 9-28, 16-17 Program attention (PA) keys 14-61, 14-67 Program function keys See Function keys Programs See NCL procedures Proofreading, NCL source code 9-4 Protected fields 14-31 PS Text Edit See TEDIT text editor PSEND CLOSE verb 15-17 PSEND OPEN verb 15-13 FORMAT operand 15-16, 15-19, 15-
Index Q QEXIT verb 2-15, 8-20 Queues, dependent 16-30 Quoted strings 4-5 R RANDOM built-in function 6-4 Range errors 7-27 RANGE operand 2-14 RANGE_ERROR error handler 7-27 Raw data, in MDO variables 10-25 Real users 16-3 Recall buffer 4-14 Record keys excluding from data 12-36 field separator 12-34 handling 12-41 including with data 12-37 specifying 12-36 specifying current 12-42 RECORD statement (DDL) 11-29 Records delimited 12-34 locking 12-65 mapped 12-29 unmapped 12-33 REDEFINES clause (DDL) 11-41 Regi
Index Request messages 15-4, 15-6, 15-16, 15-18, 15-20 mapped 15-18 unmapped 15-20 Request queue 16-30 Requester programs 15-4 Requesters 1-4, 15-2, 15-4, 15-5 PATHSEND 1-4, 15-2 Reserved words 2-2 RESET operation 12-13 Resources controlling access to 18-20 groups 18-19 locking 18-18 names 18-19, 18-20 semaphores 18-21 Response queue 16-30 RESUME core statement 2-9, 7-11, 7-20, 7-24 implicit 7-24 Retain list 8-9, 8-10 EMSPROC NCL procedure 17-15 LOGPROC NCL procedure 17-17 MSGPROC NCL procedure 17-18 RETAI
Index REVERT core statement 2-9, 7-20 ROC See Remote Operator Control ROUTE command 16-6 RUN command (TACL) 12-8 Run-time errors 7-2/28 S SAY core statement 2-10, 9-2, 9-5, 9-6, 13-6 Scheduling NCL procedures 8-2 Scope 2-5, 2-6 SCREEN COBOL 15-4, 15-5 SECCALL ADD verb 10-31, 18-3 SECCALL CHANGE verb 10-31, 18-8 SECCALL CHECK verb 18-11 SECCALL DELETE verb 18-12 SECCALL EXIT verb 18-16 SECCALL GET verb 10-30, 16-3, 18-12, 18-13 SECCALL QUERY verb 16-3, 18-13 SECCALL UPDATE verb 10-31, 18-15 SECCALL verbs 2-
Index Server classes 15-4 controlling access to 15-6/10 displaying status information 15-10 displaying users of 15-11 identifier 15-7 assigning 15-7 specifying 15-13 specifying current 15-16 making available by NCL 15-13 by NonStop NET/MASTER MS 15-6 making unavailable by NCL 15-17 by NonStop NET/MASTER MS 15-10 message structure specifying 15-16 specifying current 15-16 Server processes 1-4, 15-2, 15-4 Server programs 15-4 SERVERCLASS_SEND_ procedure call 15-5 SERVERCLASS_SEND_INFO_ procedure call 15-5 SF
Index SHOW LOCKS command 18-21 SHOW MAPS command 10-9, 11-33 SHOW NCL command 8-17, 9-17, 9-19, 9-21, 9-22, 9-29, 9-31 SHOW NCLSTAT command 8-18 SHOW OCS command 16-4 SHOW PANELS command 14-22 PRELOADED status 14-15 SHOW PARAM command 4-16, 4-17, 4-18, 14-9, 14-11, 16-37 SHOW PAUSE command 8-20 SHOW PRELOAD command 8-18 AUTOSHR status 8-15 CMDREPL status 8-13 PRELOAD status 8-8 P-UNLOAD status 8-9 RETAINED status 8-9 SHOW PSND command 15-10 SHOW PSNDUSER command 15-11 SHOW SYSPARMS command 16-37 SHOW TIMER
Index Source code, decompiled displaying 9-4, 9-33/43 multiple statements 9-37/43 single statement 9-33/36 optimization of 9-4 proofreading 9-4 Source files 4-15 Source schema file creating 11-29 creating DDL data dictionary from 11-31 SPI See Subsystem Programmatic Interface SPI-NULL clause (DDL) 11-41 SPLIT function key 9-24, 14-65 Splitting windows 9-24 Stack trace information 9-7 Standard maps 11-3/23 displaying 11-33 START command 2-8, 2-16, 6-43, 8-1, 13-1, 16-59 execution by CMD core statement 16-24
Index Strict equality, testing 5-31, 5-32 STRICT keyword, of SELECT core statement 5-31 String errors 7-27 String operator 2-3, 2-21 Strings conversion of 2-3, 2-19 errors 7-27 STRING_ERROR error handler 7-27 Structured files 12-2, 12-3 entry-sequenced 12-4, 12-5 key-sequenced 12-4 SUBMIT command 8-7, 9-29, 16-5, 16-15 unloading EMSPROC NCL procedure 17-15 unloading LOGPROC NCL procedure 17-17 Subroutines, calling 5-35 Subsystem Programmatic Interface (SPI) tokens, converting to MDO variables 11-12/19, 17-
Index SYSPARMS command (continued) NCLMAXK operand 8-21 NCLPEND operand 8-2 NCLPRSHR operand 8-8, 8-12, 8-13 EMSPROC NCL procedure 17-15 LOGPROC NCL procedure 17-17 MSGPROC NCL procedure 17-18 NCLTRLFF operand 12-34 NCLUMAX operand 8-21, 16-9 NCLXUSER operand 16-40 PPRELOAD operand 14-15, 14-17, 14-19 PRELOAD operand 8-8, 8-10, 8-12 PUNLOAD operand 14-19 UNLOAD operand 8-5, 8-13 EMSPROC NCL procedure 17-15 LOGPROC NCL procedure 17-17 MSGPROC NCL procedure 17-18 SYSTEM keyword, of ON core statement 7-6 Syst
Index System-level procedures (continued) MSGPROC NCL procedure 1-3, 1-5, 17-5 performance hints 17-10, 17-14 testing 17-14 EMSPROC NCL procedure 17-15 LOGPROC NCL procedure 17-16 MSGPROC NCL procedure 17-18 tracing 17-28 Systems Network Architecture (SNA) objects 2-17 T TACL See Tandem Advanced Control Language TACL clause (DDL) 11-41 data types, converting 11-43 TAKEOVER event, from asynchronous panels 14-73 TAL See Transaction Application Language Tandem Advanced Control Language (TACL) 8-1, 11-28 Tande
Index Terminals (continued) communication with 13-1/8 debugging 9-3, 9-17, 9-23, 9-26 restarting automatically 1-4 Termination point, of an NCL process 9-5, 9-44 Terms 2-21 Test compilation 4-13, 7-1, 9-7 Test mode NCL procedures 8-14 panel description files 14-20 performance hints 8-15, 14-20 setting off 8-15, 14-21 setting on 8-15, 14-21 THEN keyword, of IF core statement 5-25, 5-26, 5-28 THEN keyword, of SELECT core statement 5-29 TIME built-in function 6-2 Timer commands 8-6 TO keyword, of DO core stat
Index U UDB identifier 12-10 UDBCTL CLOSE command 12-17 UDBCTL file-spec command 12-12 UDBCTL OPEN command 12-10 ACCESS operand 12-14 BUFFERED operand 12-14 ID operand 12-11 INPUT operand 12-13 SEQUENTIALBUFFERING operand 12-14 SWGUID operand 12-15 UDBCTL RESET command 12-13 UDBCTL STOP command 12-15 UDBs See User databases UMS See User ID Management Services Underflow errors 7-24 Unenumerated MDO variables 10-25, 11-13, 11-14 UNLOAD operand, of SYSPARMS command 8-5, 8-13 Unloading EMSPROC NCL procedure 17
Index User databases (UDBs) 12-6 See also Files closing by NCL 12-42 by NonStop NET/MASTER MS 12-17 controlling access to 12-10/17 creating 12-8 displaying physical information 12-18 displaying status information 12-19 displaying users of 12-20 identifier assigning 12-10 specifying 12-22, 12-24 specifying current 12-38 opening by NCL 12-22/37 by NonStop NET/MASTER MS 12-10 record keys 12-36 handling 12-41 specifying current 12-42 record structure delimited 12-34 mapped 12-29 specifying 12-29 specifying cur
Index User procedure libraries 4-18, 8-10 User procedures object file 4-19 User Services, debugging 9-24 User variables 2-19, 2-20 User-defined maps 11-28/40, 12-29 adding to map file 11-32 considerations 11-40 creating 11-29/32 displaying 11-33 fields 11-35 for reply messages 15-6, 15-18 for request messages 15-6, 15-18 groups 11-35 naming 11-40 using 11-35 Users 16-3/4 communication with 13-1/8 V VALUE clause (DDL) 11-41 Variables 2-19 See also Complex variables, Compound variables, Global variables, MDO
Index Variables (continued) panels input 14-31, 14-61 output 14-32 outvar 14-32 performance hints 2-14, 2-19, 2-20, 6-33 scope 2-6 setting breakpoints on 9-5, 9-44 sharing 6-24/42 and error handlers 7-20 caller and callee interaction 6-36 debugging 9-6 performance hints 6-33 with calling 6-31 with CONTROL verb 6-24 with declaration 6-30 with RETURN core statement 6-15 stem 10-10 VARIABLE_ERROR error handler 7-28 VARS operand 2-14, 16-50, 16-59 VARTABLE verbs 2-18, 18-22/25 Vartables 18-22 performance hints
Index VERB_ERROR error handler 7-28 Virtual users 16-4 debugging NCL processes 9-28/29 executing NCL procedures with 8-7 W WHEN keyword, of SELECT core statement 4-8, 5-29, 5-31, 5-33 WHILE keyword, of DO core statement 5-12, 5-15 Windows 16-7, 16-12 debugging 9-3, 9-17, 9-22/25, 9-28 displaying panels on 14-59 logical 9-22, 9-28 splitting 9-24 swapping 9-24 WRITE verb 2-15, 9-2, 13-6 MDO variables 10-31, 16-40, 16-44/54 X X command 2-15 XOR Boolean operator 2-2, 5-25 Special characters # number sign in MD
Index #FLD panel control statement (continued) TYPE operand 14-31 VALIGN operand 14-38, 14-40 #INCLUDE panel control statement 14-1, 14-7 #NOTE panel control statement 14-1, 14-27 #OPT panel control statement 14-1 CURSOR operand 14-57 DEFAULT operand 14-29 ERRFLD operand 14-68 FMTINPUT operand 14-70, 14-71 INWAIT operand 14-58 #TRAILER panel control statement 14-1 END operand 14-53 START operand 14-53 $0 EMS collector 1-6, 17-20 $MSG map 2-20, 11-5, 11-11, 12-29, 13-8, 17-7 $NCL map 2-20, 11-3, 12-29, 16-5
Index &SYS.ERROR.STMT system variable 7-21 &SYS.ERROR.STMT_NAME system variable 7-21 &SYS.ERROR.SUBNAME system variable 7-21 &SYS.ERROR.TEXT system variable 7-21 &SYS.ERROR.VALUE system variable 7-21, 7-24, 7-25, 7-27, 7-28 &SYS.ERROR.VALUE2 system variable 7-21, 7-24, 7-27 &SYS.ERROR.VALUE2OK system variable 7-21, 7-24, 7-27 &SYS.ERROR.VALUEOK system variable 7-21, 7-24, 7-25, 7-27, 7-28 &SYS.FILE.ERROR system variable 12-21, 12-65 &SYS.FILE.ID system variable 12-21 &SYS.FILE.
Index &SYS.TERM.COLS system variable 14-6 &SYS.TERM.ROWS system variable 14-6 &SYS.WINDOW.COLS system variable 14-6, 14-56 &SYS.WINDOW.ROWS system variable 14-6, 14-56 &SYSMSG variable 7-22, 12-21, 14-69, 14-70, 14-74, 14-77, 15-11, 16-60, 18-2 ( opening parenthesis 2-3 ) closing parenthesis 2-3 * asterisk 2-3 + field character (output) 14-28 , comma 2-3 continuing lines with 4-1 - hyphen, suppressing echo with 16-30 .
