pTAL Guidelines for TAL Programmers Abstract This publication gives guidelines for writing TAL (HP Transaction Application Language) code that you can convert later to pTAL (Portable Transaction Application Language) with as few changes as possible. It is not a complete reference for either language. The reader is assumed to be an experienced TAL programmer. Product Version pTAL D44 EPTAL H01 Supported Release Version Updates (RVUs) This publication supports D44.00, G01.00, and H06.
Document History Part Number Product Version Published 117111 pTAL D40 December 1995 527256-002 pTAL D44 EPTAL H01 July 2005
pTAL Guidelines for TAL Programmers Glossary Index What’s New in This Manual ix Manual Information ix New and Changed Information Examples Figures Tables ix About This Manual xi Audience xi Related Documentation xi Notation Conventions xii 1. Overview Why a New Language? 1-1 pTAL 1-1 Compiling pTAL Programs 1-2 Deciding Whether to Convert to pTAL TAL 1-5 Unsupported TAL Features 1-6 Restricted TAL Features 1-6 1-3 2.
2. Coding Guidelines (continued) Contents 2.
2. Coding Guidelines (continued) Contents 2.
Contents 3. Differences Between TAL and pTAL (continued) 3. Differences Between TAL and pTAL (continued) Overflow Traps 3-20 Overflow Trapping Considerations for TAL and pTAL 3-21 OVERFLOW_TRAPS Directive 3-21 OVERFLOW_TRAPS Procedure Attribute 3-23 ENABLE_OVERFLOW_TRAPS Block Attribute 3-24 Returning From Function Procedures 3-27 Glossary Index Examples Example 2-1. Example 2-2. Example 2-3. Example 2-4. Example 2-5. Example 2-6. Example 2-7. Example 2-8. Example 2-9. Example 2-10. Example 2-11.
Examples (continued) Contents Examples (continued) Example 2-25. Example 2-26. Example 2-27. Example 2-28. Example 2-29. Example 2-30. Example 2-31. Example 2-32. Example 2-33. Example 2-34. Example 2-35. Example 2-36. Example 2-37. Example 2-38. Example 2-39. Example 2-40. Example 2-41. Example 2-42. Example 2-43. Example 2-44. Example 2-45. Example 2-46. Example 2-47. Example 2-48. Example 2-49. Example 2-50. Example 2-51. Example 2-52. Example 2-53. Example 2-54. Example 2-55. Example 2-56.
Examples (continued) Contents Examples (continued) Example 2-60. Example 2-61. Example 2-62. Example 2-63. Example 2-64. Example 2-65. Example 2-66. Example 2-67. Example 2-68. Example 2-69. Example 3-1. Example 3-2. Example 3-3. Example 3-4. Example 3-5. Example 3-6. Example 3-7. Example 3-8. Example 3-9. Example 3-10. Example 3-11. Example 3-12. Example 3-13. Example 3-14. Example 3-15. Example 3-16. Example 3-17. Example 3-18.
Tables Contents Tables Table 2-1. Table 2-2. Table 2-3. Table 3-1.
Contents pTAL Guidelines for TAL Programmers —527256-002 viii
What’s New in This Manual Manual Information pTAL Guidelines for TAL Programmers Abstract This publication gives guidelines for writing TAL (HP Transaction Application Language) code that you can convert later to pTAL (Portable Transaction Application Language) with as few changes as possible. It is not a complete reference for either language. The reader is assumed to be an experienced TAL programmer.
New What’s New in This Manual New • • • Routines marked with change bars in Table 3-1, Address-Conversion Routines, on page 3-2 Information about the EpTAL compiler, throughout this manual, but especially important in: ° ° Compiling pTAL Programs on page 1-2 OVERFLOW_TRAPS Directive on page 3-21 Glossary items: ° ° ° ° ° EPIC EpTAL compiler explicitly parallel instruction set computing (EPIC) release version update (RVU) RVU Changed • • • • • • • Syntax diagrams, from bracket-and-brace style t
About This Manual This manual describes the differences between the HP Transaction Application Language (TAL) and the Portable Transaction Application Language (pTAL). Throughout this manual, the nouns “TAL” and “pTAL” refer to the languages, not to the TAL compiler and pTAL compiler.
Notation Conventions About This Manual Notation Conventions • • • Hypertext Links on page xii Syntax Diagram Conventions on page xii Change Bar Notation on page xvi Hypertext Links Blue underline is used to indicate a hypertext link within text. By clicking a passage of text with a blue underline, you are taken to the location described. For example: This requirement is described under Audience on page xi. Syntax Diagram Conventions This manual presents syntax in railroad diagrams.
Syntax Diagram Conventions About This Manual Some examples of the meanings of simple diagrams are: Diagram Piece Meaning Choose item1 or item2. item1 item2 VST407.vsd Choose item1, item2, or neither. item1 item2 VST408.vsd Specify item one or more times, separating occurrences with commas. item , VST409.vsd Specify item at most n times. item n VST742.vsd Note.
Syntax Diagram Conventions About This Manual Spacing rules are: • If the arrow between two diagram pieces is labelled “ns,” put no spaces between the syntactic items that they represent. For example: ns volume $ VST420.vsd means that you type: $NEWVOL not $ NEWVOL • An “ns” on the top line of a choice structure applies to the lower lines in the choice structure as well. For example: ns ns " RETURN^SORT^ERRORS " RETURN_SORT_ERRORS_ VST185.
Syntax Diagram Conventions About This Manual • If two diagram pieces are separated by a separator character, separating the syntactic items that they represent by spaces is optional. For example: integer1 MULTIPLY , integer2 VST411.vsd means that you type: MULTIPLY 3,4 or MULTIPLY 3, 4 • If a diagram piece is immediately followed by a period, putting spaces between the syntactic item and the period is optional. For example: END PROGRAM program-name . VST374.
Change Bar Notation About This Manual Change Bar Notation Change bars are used to indicate substantive differences between this edition of the manual and the preceding edition. Change bars are vertical rules placed in the right margin of changed portions of text, figures, tables, examples, and so on. Change bars highlight new or revised information. For example: The message types specified in the REPORT clause are different in the COBOL environment and the Common Run-Time Environment (CRE).
1 Overview This manual gives guidelines for writing programs in the HP Transaction Application Language (TAL). If you follow these guidelines in your TAL program, you will be able to convert it to the Portable Transaction Application Language (pTAL) more easily than if you use all of the TAL features.
Compiling pTAL Programs Overview Compiling pTAL Programs Note. You can use pTAL object files only on D40 RVUs and later of the NonStop operating system. Figure 1-1 on page 1-3 shows that you can: • Use the pTAL compiler to check your pTAL program’s syntax and then compile your pTAL program with the TAL compiler to create a TNS object file. The pTAL compiler displays messages that identify the majority of syntax errors and include information to help diagnose each error.
Deciding Whether to Convert to pTAL Overview Figure 1-1. Compiling pTAL Source Code pTAL Source Code pTAL Compiler With SYNTAX Directive pTAL Compiler EpTAL Compiler Native Compilers TAL Compiler (D40 or later) TNS Object File TNS/R Object File TNS/E Object File Native Object Files Accelerator OCA Accelerated Object File for TNS/R Architecture Accelerated Object File for TNS/E Architecture VST001.
Deciding Whether to Convert to pTAL Overview Figure 1-2 on page 1-4 shows a model of a generic application. Processor time for the application is divided between time spent in TAL code and time spent in system code. The application might call the file system to perform the following sequence of tasks: 1. 2. 3. 4.
TAL Overview TAL HP and its customers have written most system software in TAL.
Unsupported TAL Features Overview Finally, TAL does little integrity checking when you store an address into a pointer. You must ensure, therefore, that the address you store into a pointer references the correct offset in the correct data area. In TAL, you can store any value in any pointer provided only that the length of the value is the same as the length of the pointer—16 bits or 32 bits. Unsupported TAL Features Not all TAL features are supported in pTAL.
2 Coding Guidelines This section presents guidelines you can use to write TAL code that will be easier to convert to pTAL than if you used all of the features of TAL.
Guidelines Summary Coding Guidelines Topic Guideline (page 2 of 5) @ Operator With Procedure Names on page 2-25 Do not apply the @ operator to a procedure name and treat the resultant value as a 16bit integer. (This does not apply to subprocedure names or to labels.) Address Arithmetic on page 2-16 Use arithmetic operations on pointers only if the result of the operation yields another address or if the result is the number of elements between two pointers.
Guidelines Summary Coding Guidelines Topic Guideline (page 3 of 5) Dynamic Procedure Calls on page 2-33 Use procedure pointers instead of CODE(DPCL) statements. Equivalenced Variables and Indirect Pointers on page 2-23 Do not equivalence an integer to the implicit pointer of an indirect array or indirect structure. Equivalenced Variables and Memory on page 2-8 Equivalenced variables can reference only the memory contained within the previous variable.
Guidelines Summary Coding Guidelines Topic Guideline (page 4 of 5) P Register in Stack Marker on page 2-28 Do not change a procedure’s return destination by storing a value into the P register in the stack marker. Parameter Accesses Using Based-Address Equivalenced Declarations, Indexing, and Pointers on page 2-27 Access parameters only by referencing the name of the parameter.
Compilers Coding Guidelines Topic Guideline (page 5 of 5) Saving the P, L, and S Registers on page 2-53 Do not implement state machines by saving and restoring the P, L, and S registers. Signed (Arithmetic) Left Shifts on page 2-56 The sign bit is not preserved by signed (arithmetic) left shifts. Signed and Unsigned 16-Bit Addition, Subtraction, and Negation on page 2-9 Use unsigned operators if you expect modulo-216 results.
DO_PTAL Directive Coding Guidelines Example 2-1. PTAL Conditional Compilation Toggle ?IFNOT PTAL DEFINE an_int = INT#; ?ENDIF PTAL ?IF PTAL DEFINE an_int = INT(32)#; ?ENDIF PTAL You cannot specify the PTAL toggle in a SETTOG, RESETTOG, or DEFINETOG directive. DO_PTAL Directive Guideline: Use the DO_PTAL directive to enable additional TAL features. If you specify the DO_PTAL directive, D40 and later TAL compilers recognize additional constructs that are required to fully support the pTAL language.
Referencing Variables and Parameters Coding Guidelines Example 2-2 on page 2-6 does not work in a pTAL program running as a native process because native compilers optimize the time required to access variables and parameters by: • • Arranging the items in memory for optimal access (the actual order of the variables in memory might differ from the order in which you declare them) Inserting filler between items To ensure the position of one variable relative to another in pTAL, use elements of an array,
Equivalenced Variables and Memory Coding Guidelines Example 2-5. Zero in Next Field of Structure Ensures That Scan Stops STRUCT .s; BEGIN STRING scan_buff [0:79]; STRING stopper; END; ! Buffer for scanning stopper ! immediately follows buffer s.stopper := 0; SCAN s.scan_buff WHILE " "; ! If line is blank, ! zero in s.stopper stops scan Equivalenced Variables and Memory Guideline: Equivalenced variables can reference only the memory contained within the previous variable.
Arithmetic Operations Coding Guidelines Arithmetic Operations Topics: • • Signed and Unsigned 16-Bit Addition, Subtraction, and Negation on page 2-9 Overflow Traps on page 2-10 Signed and Unsigned 16-Bit Addition, Subtraction, and Negation Guideline: Use unsigned operators if you expect modulo-216 results.
Overflow Traps Coding Guidelines Overflow Traps Guideline: Do not assume that overflow causes a trap on intermediate operators within an expression. If traps are enabled in a TAL program, an overflow exception causes an immediate trap. In Example 2-6 on page 2-10, the addition operator causes overflow and a trap occurs. The program retains control only if it has established a trap handler; otherwise, the program abends. Example 2-6.
Pointers and Addresses Coding Guidelines • • The granularity of the data address, which is one of: ° ° A byte address A word address The width of the address, which is one of: ° ° 16 bits 32 bits Table 2-1 on page 2-11 lists the 10 address types in pTAL.
Pointers and Addresses Coding Guidelines Table 2-1. pTAL Address Types (page 2 of 2) Example Pointer or Declaration Object Data Type Data Location STRING .SG sgb; STRING INT .SGX sgw; Address Type Granularity Width1 System Global Segment SGBADDR byte 16 bits INT System Global Segment SGXWADDR 16-bit word 16/32 bits STRING .
@ Operator Applied to Variables Coding Guidelines Topics: • • • • • • • • • • • • • @ Operator Applied to Variables on page 2-13 32-Bit Addresses on page 2-14 Addresses and Integer Variables on page 2-14 Address Variables on page 2-14 Addresses and Integer Expressions on page 2-15 Address Conversions on page 2-15 Address Arithmetic on page 2-16 Incrementing and Decrementing Pointers on page 2-17 Comparing Addresses to Addresses on page 2-19 Comparing Addresses to Constants on page 2-19 Addresses Are Ind
32-Bit Addresses Coding Guidelines 32-Bit Addresses Guideline: Create 32-bit addresses only to reference data in extended data segments. In TAL, your program can reference all data with a 16-bit address except data in extended memory, for which you must use a 32-bit address. On TNS architecture, you can also create 32-bit addresses to reference data in other segment types, such as in the user data segment. Note.
Addresses and Integer Expressions Coding Guidelines Addresses and Integer Expressions Guideline: Include only constant operands in an integer expression whose value is assigned to a 16-bit pointer. In TAL, the expression you store into a 16-bit pointer can include both constant and nonconstant integer values. In pTAL, you can store an integer into a 16-bit pointer only if the integer is a constant expression. Example 2-10. Valid Assignments DEFINE offset = 14; LITERAL distance = 20; INT .
Address Arithmetic Coding Guidelines Table 2-2. Address Conversions (page 2 of 2) Conversion Expression Result Type Example $DBLL(0, BADDR ) EXTADDR STRING .p; STRING .EXT s := $DBLL(0, @p); $UDBL(WADDR ) ‘<<‘ 1 EXTADDR INT .p; INT .EXT s := $UDBL(@p) ‘<<‘ 1; $DBLL(0, WADDR ) ‘<<‘ 1 EXTADDR INT .p; INT .EXT s := $DBLL(0, @p) ‘<<‘ 1; pTAL also supports high-level data type conversions. For details, see AddressConversion Routines on page 3-1.
Incrementing and Decrementing Pointers Coding Guidelines Table 2-3. Valid Arithmetic Operations on Addresses General Expression Result Type Example Meaning atype 1 ‘+’ INT atype @wp := @wp ‘+’ n; Increment @WP by n words. INT ‘+’ atype 1 atype @bp := n ‘+’ @bp; Increment @BP by n bytes. atype 1 ‘-’ INT atype @wp := @wp ‘-’ n; Subtract n bytes from a word pointer. EXTADDR + INT(32) EXTADDR Add 32-bit integer to an extended pointer.
Incrementing and Decrementing Pointers Coding Guidelines Example 2-12. Incrementing a Pointer STRUCT .s[0:9]; BEGIN INT i; INT(32) j; INT k; STRING l; END; INT .p(s) := @s; @p := @p '+' 5; @p := @p '+' $LEN(s)/2; @p := @p[1]; ! Must know size of s ! Need not know size of s, but complex ! Need not know size of s, simpler You can use indexing whenever the number of elements you are stepping is an integral multiple of the size of an array element, including structure arrays.
Comparing Addresses to Addresses Coding Guidelines Comparing Addresses to Addresses Guideline: Use only those relational operators that are defined for pTAL, as described in this guideline. In TAL, you can compare two addresses using any relational operator. In pTAL, you can compare two addresses according to the following rules: • • • Compare extended addresses (addresses whose data type is EXTADDR) using only signed relational operators (<, <=, =, <>, >=, >).
Addresses Are Indivisible Coding Guidelines Example 2-15. Comparing Addresses to Constants INT .i; STRING .s; INT .EXT e; STRING .SG sgb; IF IF IF IF @i '>' 0 THEN...; @s <> 0 THEN...; @e = 0d THEN...; @sgb = 0 THEN...; ! ! ! ! @i is WADDR, needs unsigned comparison @s is BADDR, signed <> (and =) OK @e is EXTADDR, needs signed = @sgb is SGBADDR, signed = OK In general, compare addresses only to zero or to a value that you use to represent a nil value. Do not depend on constant memory addresses.
Addresses Are Absolute Coding Guidelines Example 2-17. Comparing Two Addresses STRING .a[0:90]; STRING .ptr; BADDR max_addr := @a '+' 79; SCAN a until " " -> @ptr; IF @ptr '>' max_addr THEN ... You might want to use a SCAN or RSCAN statement to scan a string of characters. The SCAN or RSCAN statement, however, can scan strings only in the user data segment—the pointer to the data cannot be an extended pointer.
Addresses Are Absolute Coding Guidelines Example 2-18 on page 2-21 has two statements that are not valid in a pTAL program that runs as a native process: • • The IF statement compares the address in the pointer xptr to %2000000d. The comparison assumes that addresses that are less than %2000000d are in the user data segment, and that addresses equal to or greater than %2000000d are in an extended data segment.
Equivalenced Variables and Indirect Pointers Coding Guidelines Example 2-20. Scanning Algorithm DEFINE found = 1#; INT PROC scan_until(ptr:cnt, search_char); STRING .EXT ptr; INT cnt; STRING .search_char; BEGIN STRING .
Procedures, Subprocedures, and Labels Coding Guidelines You can equivalence a pointer to the implicit pointer of an indirect array or indirect structure, as in Example 2-22 on page 2-24. Example 2-22. Equivalencing a Pointer to an Indirect Pointer INT .a[0:99]; INT .p = a; In Example 2-22 on page 2-24, p is a read-only pointer—you cannot store into the pointer. but you can use the pointer to read the address of the indirect array or structure, or to read or write the data of the array or structure.
@ Operator With Procedure Names Coding Guidelines • • • • • • • • • P Register in Stack Marker on page 2-28 Extensible and Variable Procedures: Dynamic Calls on page 2-29 Reading and Altering Parameter Masks on page 2-29 $OPTIONAL Routine on page 2-30 Building Parameter Masks on page 2-31 Returning a Value From a Function on page 2-32 RETURN Statement Must Appear in Every Function on page 2-32 Returning From a Function That Does Not Specify a RETURN Statement on page 2-32 Dynamic Procedure Calls on page
Stack Marker Accesses Using Based-Address Equivalenced Declarations, Indexing, and Pointers Coding Guidelines Stack Marker Accesses Using Based-Address Equivalenced Declarations, Indexing, and Pointers Guideline: Do not read or write the contents of the stack marker. In TAL, you can use base-address equivalencing to reference information stored in the TNS stack marker, which describes the caller’s environment.
Parameter Accesses Using Based-Address Equivalenced Declarations, Indexing, and Pointers Coding Guidelines Example 2-25. Using Indexing and Pointers to Access Stack Marker (TAL Only) PROC p; BEGIN INT .env_reg(env_layout); INT t; @env_reg := @t '-' 3; IF env_reg.trap_enable THEN BEGIN ...
Carry Bit in ENV in Stack Marker Coding Guidelines In pTAL, a procedure cannot access an overflow bit because the native architecture does not have an analog to the TNS overflow bit. If you run a pTAL program that attempts to set this bit as a native process, the results are undefined. If you have procedures that set or reset the overflow bit in the stack marker copy of the ENV register, you must redesign the procedures’ algorithms.
Extensible and Variable Procedures: Dynamic Calls Coding Guidelines Example 2-27. Changing Return Location Without Using TNS Stack Marker INT PROC p_prime(i, j, k); INT i, .j, k; BEGIN ... RETURN case-selector-value; END; PROC p(i, j, k); INT i, .j, k; BEGIN CASE p_prime(i, j, k) of BEGIN ...
$OPTIONAL Routine Coding Guidelines $OPTIONAL Routine Guideline: Use the $OPTIONAL built-in routine to control whether parameters are passed to variable and extensible procedures. The built-in routine $OPTIONAL, available in both TAL and pTAL, enables your program to determine at run time whether to pass a particular parameter to a variable or extensible procedure. In Example 2-28 on page 2-30, procedure p is a front end to procedure q and passes a parameter to q only if a parameter was passed to p.
Building Parameter Masks Coding Guidelines Building Parameter Masks Guideline: Use procedure pointers, rather than building parameter masks, for variable and extensible procedures. Do not build parameter masks. If you call a procedure that has a formal parameter of type PROC and the procedure you pass as the actual parameter specifies a VARIABLE, EXTENSIBLE, or RETURNSCC attribute, change the PROC formal parameter to a procedure pointer (PROCPTR) formal parameter.
Returning a Value From a Function Coding Guidelines Returning a Value From a Function Guideline: Always specify a function’s return value as part of the RETURN statement. In TAL, you can explicitly push a function’s value onto the stack and return from the function using an expressionless RETURN statement, as Example 2-32 on page 2-32. Example 2-32.
Dynamic Procedure Calls Coding Guidelines In pTAL, your program traps with an Instruction Failure if a function attempts to return because it arrives at the end of the function code. You must return from a function by explicitly executing a RETURN statement. Note. If you compile your program with the DO_PTAL Directive on page 3-5, functions that execute down to the END that closes a function’s body do not cause the program to abort.
Dynamic Procedure Calls Coding Guidelines Example 2-35. Dynamic Procedure Calls With PROC Parameters PROC x1(p1, p2); INT p1, p2; BEGIN ... END; PROC x2(p1, p2); INT p1, p2; BEGIN ... END; PROC x3(p1, p2); INT p1, p2; BEGIN ... END; PROC p(a_proc); PROC a_proc; BEGIN ... CALL a_proc(1, 2); END; If the procedure name you pass as an actual parameter specifies a VARIABLE, EXTENSIBLE, or RETURNSCC attribute, specify a procedure pointer as the formal parameter, as in Example 2-36 on page 2-34. Example 2-36.
Parameters Coding Guidelines Example 2-36. Dynamic Procedure Calls With Procedure Pointers (page 2 of 2) PROC p(a_proc); PROCPTR a_proc(a1, a2) EXTENSIBLE; INT a1, a2; END PROCPTR; BEGIN ... CALL a_proc(1, 2); END; For more information, see Procedure Pointers on page 3-6.
Formal Value Parameters of Data Type STRING Coding Guidelines Formal Value Parameters of Data Type STRING Guideline: Do not declare formal value parameters of data type STRING. In TAL, a procedure can declare a formal value parameter whose data type is STRING.
Using STACK Statements to Pass Parameters Coding Guidelines Using STACK Statements to Pass Parameters Guideline: Pass parameters to procedures and functions using only high-level constructs. Do not pass parameters by pushing them onto the stack with STACK and CODE statements. pTAL does not support the STACK or CODE statements. Example 2-37 on page 2-37 is valid in TAL but not in pTAL. Example 2-37. Using STACK and CODE Statements to Pass Parameters (TAL Only) INT PROC p(i); INT i; BEGIN ...
Parameters and Local Variables Coding Guidelines Example 2-39. Not Assuming That Parameters Are Stored Consecutively PROC g(i, j, k, l, m, n); INT i, j, k, l, m, n; BEGIN i := 0; j := 0; k := 0; l := 0; m := 0; n := 0; ... END; Parameters and Local Variables Guideline: Do not assume that there is a relationship between where a procedure’s parameters and where its local variables are stored in memory. Example 2-40 on page 2-38 uses the pointer i to reference the value of a parameter. Example 2-40.
Parameters and Structure Layouts Coding Guidelines Parameters and Structure Layouts Guideline: Use structure pointers as formal parameters, rather than definition or referral structures. In TAL, you can declare a parameter whose data type is a definition structure—that is, you declare the structure layout in the formal parameter declaration, as in Example 2-41 on page 2-39. Example 2-41. Definition Structure as Formal Parameter (TAL Only) PROC p(s); STRUCT .s; BEGIN INT a; INT b; END; BEGIN ...
Hardware Indicators Coding Guidelines In pTAL, you cannot apply an @ operator to a procedure name or procedure pointer name that you pass as an actual parameter, unless the formal parameter is type PROCADDR, in which case the @ operator is required; therefore, in pTAL, an @ operator is: • • Invalid if the formal parameter is a PROC or PROCPTR Required if the formal parameter is a PROCADDR Example 2-43.
Hardware Indicators Coding Guidelines In TAL, you can reference a condition code anywhere an expression is valid. The statements in Example 2-44 on page 2-41 are all valid in TAL, but none are valid in pTAL. Example 2-44. Referencing Condition Codes (TAL Only) a := <; CALL p( > ); WHILE = DO BEGIN ... END; DO ... READX ( ...
Hardware Indicators: Test Only in an IF Statement Coding Guidelines Hardware Indicators: Test Only in an IF Statement Guideline: Reference hardware indicators only in the conditional expression of an IF statement. In TAL, you can reference a hardware indicator in any expression. You must ensure that the hardware indicator reflects the condition that you expect at the location in your code where you reference it.
Hardware Indicator: Must Be First Operand Coding Guidelines Example 2-47. Invalid Condition Code Test After Arithmetic Operation IF i + j <> k THEN BEGIN USE x; IF > THEN ... ! ERROR: condition code must be tested ! immediately after assignment statement Example 2-48 on page 2-43 follows the guidelines. READX is a file system procedure. Example 2-48. Valid References to Hardware Indicators CALL READX( fn, buffer, buffer_len, bytes_read); IF <> THEN ... ! OK i := i + 1; IF $OVERFLOW THEN ...
Hardware Indicators: Where to Test Coding Guidelines Hardware Indicators: Where to Test Guideline: Test a hardware indicator only after a statement that sets or resets it. In TAL you can test the carry bit after any statement. The value that you test might not have been set in the preceding statement, as in Example 2-51 on page 2-44. Example 2-51. Valid Test of a Hardware Indicator INT i := 0; ... i := i * 1; IF $CARRY THEN ...
Hardware Indicators: Test Only the Condition Code in a Nest of IF Statements Coding Guidelines Example 2-53. Testing Condition Code in ELSE Part of Nested IF Statement i := i + 1; IF > THEN BEGIN ... END ELSE IF < AND i <> 10 THEN BEGIN ...
Hardware Indicators: Testing in a Called Procedure Coding Guidelines Example 2-56. Valid $OVERFLOW Test (pTAL) ?NOOVERFLOW_TRAPS ! Disable overflow traps temp := i + 1; IF $OVERFLOW THEN ! Test for overflow BEGIN ! Handle overflow condition END ELSE BEGIN i := i + 1; ! Reestablish cond code and do assignment IF <> THEN ... ! OK END; ?OVERFLOW_TRAPS ! Enable overflow traps Example 2-57. Valid $CARRY Test temp := i '+' 1; IF NOT > THEN BEGIN i := i '+' 1; IF $CARRY THEN ... ...
Hardware Indicators: Testing in a Called Procedure Coding Guidelines Example 2-58. Testing a Hardware Indicator in a Called Procedure (TAL Only) PROC check_read; BEGIN IF <> THEN ... ... END; ! Test condition code returned by READX proc PROC a; BEGIN CALL readx(...); CALL check_read; END; pTAL programs running as native processes cannot set a hardware indicator in one procedure and test its value in a called procedure.
Hardware Indicators: Accessing Across Procedure Calls Coding Guidelines Hardware Indicators: Accessing Across Procedure Calls Guideline: Do not set a hardware indicator and test it upon resuming execution after calling another procedure.
Returning a Condition Code Coding Guidelines Example 2-61. RETURNSCC Procedure Attribute PROC p CALLABLE, RETURNSCC; BEGIN INT i; ... RETURN ,i; END; The TAL compiler recognizes the RETURNSCC attribute, accepts the extended syntax of the RETURN statement, and sets the condition code according to the value you specify. In pTAL, both cc_expression and the RETURNSCC attribute are required if either is present. Note.
Condition Code: Saving the Value in a Variable Coding Guidelines Example 2-62. Returning a Condition Code INT PROC p; BEGIN RETURN int_value; END; REAL PROC q; BEGIN RETURN real_value; END; CALL p; IF <> THEN ... ! OK: p returns value of type INT CALL q; IF <> THEN ... ! ERROR: q returns value of type REAL Condition Code: Saving the Value in a Variable Guideline: Do not save the value of a condition code by assigning its value to a variable. In TAL, you can assign the condition code to a variable.
Overflow Traps Must Be Disabled to Test $OVERFLOW Coding Guidelines Overflow Traps Must Be Disabled to Test $OVERFLOW Guideline: Do not test $OVERFLOW in portions of your code in which you have enabled overflow traps. In TAL, you can test $OVERFLOW anywhere in your code. The TAL compiler generates object code that tests the current value of the overflow bit in the ENV (environment) register. In pTAL, you can test $OVERFLOW only in those portions of your code in which overflow traps are disabled.
TNS Registers Coding Guidelines In TAL, you can use a base-address equivalenced declaration to create an identifier that references a data item at: • • • A positive offset from the beginning of the user data segment (G-relative) A positive or negative offset from the beginning of a procedure’s local data (Lrelative) A negative offset from the beginning of a subprocedure’s local data (S-relative) pTAL does not support based-address equivalenced declarations.
TNS Registers and Trap Handlers Coding Guidelines TNS Registers and Trap Handlers Guideline: Use registers in trap handlers only in programs running as TNS processes. Do not attempt to change the values of TNS registers in a trap handler and then resume running your program. For versions of pTAL programs that run as TNS processes, access the values of TNS registers only to print them or to save them in a log file.
USE and DROP Statements Coding Guidelines USE and DROP Statements Guideline: Always assume that the value of a USE variable is initially undefined. TAL programs can rely on the ways in which USE and DROP statements use TNS registers. Within the DO-UNTIL loop in the following example, the program executes, in succession, a DROP statement, a USE statement, a second DROP statement, and a second USE statement.
STACK, STORE, and CODE Statements Coding Guidelines STACK, STORE, and CODE Statements In TAL, you can use CODE statements to execute specific TNS hardware instructions. pTAL does not support CODE statements, STACK statements, or STORE statements. Topics: • • STACK and STORE Statements on page 2-55 CODE Statements on page 2-55 STACK and STORE Statements Guideline: Avoid STACK and STORE statements. pTAL does not support the TAL STACK or STORE statement. Instead, use temporary variables wherever possible.
Signed (Arithmetic) Left Shifts Coding Guidelines Signed (Arithmetic) Left Shifts Guideline: The sign bit is not preserved by signed (arithmetic) left shifts. In TAL, the signed left-shift operator (<<) performs an arithmetic left shift, shifting left all of the bits in a 16-bit word except the left-most bit (the sign bit). The left-most bit retains the value it had before the shift. The unsigned left-shift operator ('<<') shifts all bits including the left-most bit of the 16-bit word.
Signed (Arithmetic) Left Shifts Coding Guidelines Example 2-69. Signed Left-Shift Procedures (page 2 of 2) INT(32) PROC ashift32(a, cnt); INT(32) a; INT cnt; ! 32-bit signed left shift BEGIN STRUCT s = a; BEGIN UNSIGNED(1) sign_bit; UNSIGNED(31) rest; END; s.rest := s.
Coding Guidelines Signed (Arithmetic) Left Shifts pTAL Guidelines for TAL Programmers —527256-002 2- 58
3 Differences Between TAL and pTAL This section describes the following features: • • • • • • • Address-Conversion Routines on page 3-1 Address-Type Variables on page 3-4 DO_PTAL Directive on page 3-5 Procedure Pointers on page 3-6 Dynamically Selected Procedure Calls on page 3-18 Overflow Traps on page 3-20 Returning From Function Procedures on page 3-27 Address-Conversion Routines In pTAL and in D40 and later releases of TAL, you can use address-type conversion routines.
Address-Conversion Routines Differences Between TAL and pTAL Table 3-1. Address-Conversion Routines Converts address ...
Differences Between TAL and pTAL Address-Conversion Routines Example 3-1. Address-Conversion Routines STRING .s; EXTADDR e; e := $BADDR_TO_EXTADDR(@s); STRING .s; WADDR w; w := $BADDR_TO_WADDR(@s); PROC p(x); STRING .EXT x; BEGIN STRING .j; @j := $EXTADDR_TO_BADDR(@x); END; PROC p(x); INT .EXT x; BEGIN INT .j; @j := $EXTADDR_TO_WADDR(@x); END; STRING .SG s; EXTADDR e; e := $SGBADDR_TO_EXTADDR(@s); STRING .SG s; SGWADDR w; w := $SGBADDR_TO_SGWADDR(@s); INT .
Address-Type Variables Differences Between TAL and pTAL Address-Type Variables In pTAL and in D40 and later releases of TAL, you can declare variables whose data type is an address type. The address types are shown in Table 2-1 on page 2-11. Example 3-2 on page 3-4 has a declaration for each of the address types and examples of how you might use them.
DO_PTAL Directive Differences Between TAL and pTAL DO_PTAL Directive Note. The TAL compiler accepts this directive as of product version D40. The native compilers ignore it. The DO_PTAL directive enables features of the TAL compiler that provide compatibility with pTAL. These features include changes and additions to the syntax as well as changes to the run-time behavior of certain TAL constructs. DO_PTAL SYNTAX NODO_PTAL POPDO_PTAL PUSHDO_PTAL VST003.
Differences Between TAL and pTAL Procedure Pointers Without SYNTAX, DO_PTAL has the preceding effects and also: • • • Function procedures and function subprocedures must return to their callers by executing a RETURN statement. Your program aborts if it reaches the end of a function’s code. (If you specify DO_PTAL SYNTAX or you do not specify a DO_PTAL directive, a function that reaches the end of its code returns a value of 0 to its caller as in pre-D20 TAL releases.
Declaring Procedure Pointers Differences Between TAL and pTAL Declaring Procedure Pointers The syntax of a procedure pointer declaration is: procptr-name PROCPTR return-type formal-param-names formal-param-spec attributes END ; PROCPTR VST600.
Declaring Procedure Pointers Differences Between TAL and pTAL formal-param-names is the identifier of a formal parameter. A procedure can have up to 32 formal parameters, with no limit on the number of words of parameters and has the form: ( ) param-name param-pair , VST210.vsd param-name is the identifier of a formal parameter. A procedure can have up to 32 formal parameters, with no limit on the number of words of parameters.
Declaring Procedure Pointers Differences Between TAL and pTAL attributes MAIN INTERRUPT RESIDENT CALLABLE PRIV VARIABLE EXTENSIBLE ( count ) RETURNSCC OVERFLOW_TRAPS NOOVERFLOW_TRAPS LANGUAGE C COBOL FORTRAN PASCAL UNSPECIFIED VST635.vsd Note. The EpTAL compiler ignores INTERRUPT. For descriptions of attributes, see the pTAL Reference Manual.
Declaring Procedure Pointers Differences Between TAL and pTAL formal-param-spec is a formal parameter specification: procptr param-type identifier . .EXT .SG .SGX ( referral ) , VST712.vsd procptr is a pointer identifier. param-type is any data type described in the data-type parameter of this syntax description. .(period) is the standard indirection symbol and denotes 16-bit pointer. .EXT is the extended indirection symbol and denotes an extended (32-bit) pointer. .
Declaring Procedure Pointer Variables Differences Between TAL and pTAL For most situations, you can use the .SGX indirection symbol. You might need to use the .SG indirection symbol if you use CISC instructions that require that pointers to system data be 16 bits (for example, time list instructions). identifier is a standard pTAL identifier referral is the name of a previously declared structure or structure pointer. You must include referral if the formal parameter identifier is the name of a structure.
Declaring Procedure Pointer Variables Differences Between TAL and pTAL Considerations: • • • • You can declare a procedure pointer anywhere a data declaration is valid. The address type of a procedure pointer is PROCADDR. The object data type of a function procedure pointer is the data type returned by the function. You can initialize procedure pointers declared at the local and sublocal levels but not at the global level.
Differences Between TAL and pTAL Using Procedure Pointer Variables Using Procedure Pointer Variables Assign values to a procedure pointer using an assignment statement. The left side of the assignment consists of an @ operator applied to the identifier of a procedure pointer. The right side is an expression that evaluates to a PROCADDR.
Declaring Procedure Pointer Structure Fields Differences Between TAL and pTAL Declaring Procedure Pointer Structure Fields You can declare procedure pointer fields in structure declarations. Use the following syntax: procptr ; = prev-identifier VST715.vsd procptr is a procedure pointer declaration as previously defined in this section. prev-identifier is the identifier of a field in the same structure or substructure as procptr and at the same structure level.
Differences Between TAL and pTAL Declaring Procedure Pointer Structure Fields Example 3-6. Procedure Pointers in Template Structure STRUCT s1(*); BEGIN REAL PROCPTR f(x); REAL x; END PROCPTR; REAL PROCPTR g(x); INT x; END PROCPTR = f; REAL PROCPTR h(x); FIXED x; END PROCPTR = g; END; Example 3-7 on page 3-15 uses structure s1 from Example 3-6 on page 3-15. Example 3-7.
Declaring PROC Formal Parameters Differences Between TAL and pTAL Example 3-8.
Differences Between TAL and pTAL Declaring Procedure Pointer Formal Parameters In Example 3-9 on page 3-16, the TAL compiler cannot verify that p1 has the same attributes and parameter definitions as the procedure called from p2; therefore, you must ensure that the procedure you pass to p2 has the same number of parameters, the same parameter types, and the same procedure attributes as the procedure that p2 expects when it calls its parameter, p.
Differences Between TAL and pTAL Dynamically Selected Procedure Calls Example 3-11. Procedure Pointers INT i; REAL r; REAL .EXT r2; STRUCT s1 [0:9]; BEGIN REAL PROCPTR f(x); REAL x; END PROCPTR; END; PROC p (i, j) EXTENSIBLE, CALLABLE; INT i, .EXT j; FORWARD; PROCPTR a (a, b) EXTENSIBLE, CALLABLE; INT a, .EXT b; END PROCPTR; PROCPTR c (p); REAL PROCPTR p (x); REAL x; END PROCPTR; BEGIN END PROCPTR; REAL PROCPTR d (x); REAL x; END PROCPTR; @a := @p; @d := @s1[2].f; @s1[3].
Dynamically Selected Procedure Calls Differences Between TAL and pTAL All of the examples: • • Have calls based on the device type of a terminal Use these declarations: LITERAL dev_6530, dev_3270, dev_conv; INT device_type; PROCPTR p(i, j); INT i, j; END PROCPTR; PROC device_6530(i, j); INT i, j; EXTERNAL; PROC device_3270(i, j); INT i, j; EXTERNAL; PROC device_conv(i, j); INT i, j; EXTERNAL; You cannot create an array of procedure pointers, but you can create an array of structures that have procedure
Overflow Traps Differences Between TAL and pTAL Example 3-14. Array of Procedure Addresses Declare the array of procedure pointers: PROCPTR p(i, j); INT i, j; END PROCPTR; PROCADDR pa[dev_6530:dev_conv]; ! Array of procedure addresses Initialize the array: pa [dev_6530] := @device_6530; pa [dev_3270] := @device_3270; pa [dev_conv] := @device_conv; Select a procedure to call: @p := pa[device_type]; Overflow Traps In TAL, overflow traps are supported by bits in the ENV register.
Overflow Trapping Considerations for TAL and pTAL Differences Between TAL and pTAL Overflow Trapping Considerations for TAL and pTAL In a pTAL program that you run as a native process, the overflow trapping directives, procedure attributes, and BEGIN-END block attributes directly control the trapping behavior of your program.
Differences Between TAL and pTAL OVERFLOW_TRAPS Directive NOOVERFLOW_TRAPS disables overflow traps for procedures and BEGIN-END blocks that do not specify an attribute to enable overflow traps. This is the default for the EpTAL compiler. POPOVERFLOW_TRAPS pops the top item from the compile-time stack of OVERFLOW_TRAPS values and sets the current value of OVERFLOW_TRAPS to the value popped off the stack.
Differences Between TAL and pTAL OVERFLOW_TRAPS Procedure Attribute An OVERFLOW_TRAPS procedure attribute overrides an OVERFLOW_TRAPS directive. A block-level ENABLE_OVERFLOW_TRAPS attribute overrides a procedure-level OVERFLOW_TRAPS attribute as well as an OVERFLOW_TRAPS directive. OVERFLOW_TRAPS Procedure Attribute In pTAL, you can use the OVERFLOW_TRAPS and NOOVERFLOW_TRAPS procedure attributes to enable or disable traps for a procedure.
ENABLE_OVERFLOW_TRAPS Block Attribute Differences Between TAL and pTAL ENABLE_OVERFLOW_TRAPS Block Attribute In both TAL and in pTAL, you can use the following syntax to specify whether you want to enable or disable overflow traps within the scope of a BEGIN-END block: BEGIN : ENABLE_OVERFLOW_TRAPS DISABLE_OVERFLOW_TRAPS VST682.vsd Program behavior within a block that specifies a block-level attribute is the same in TAL and in pTAL—that is, in TNS and native processes.
Differences Between TAL and pTAL ENABLE_OVERFLOW_TRAPS Block Attribute Considerations When the operating system starts a program, it enables overflow traps for that program. For a pTAL program running as a native process, you can specify any combination of directives, procedure attributes, or block-level attributes.
Differences Between TAL and pTAL ENABLE_OVERFLOW_TRAPS Block Attribute When to Use Overflow Trap Attributes A TAL program can enable or disable overflow traps only using block-level attributes. Each time you enter or exit a block that specifies a block-level trapping attribute, your program executes a small number of TNS machine instructions that set or reset a hardware bit to enable or disable overflow traps. The TAL compiler does not generate machine code for procedure or subprocedure attributes.
Returning From Function Procedures Differences Between TAL and pTAL Example 3-18. ENABLE_OVERFLOW_TRAPS and DISABLE_OVERFLOW_TRAPS Block Attributes and BEGIN-END Blocks PROC p; BEGIN: ENABLE_OVERFLOW_TRAPS ... END; ! Ensure traps are enabled PROC q; BEGIN SUBPROC q; BEGIN: DISABLE_OVERFLOW_TRAPS ... END; ...
Differences Between TAL and pTAL Returning From Function Procedures pTAL Guidelines for TAL Programmers —527256-002 3- 28
Glossary accelerate. To speed up emulated execution of a TNS object file by applying the Accelerator for TNS/R system execution or the TNS Object Code Accelerator (OCA) for TNS/E system execution before running the object file. accelerated mode. See TNS accelerated mode. accelerated object code.
indirection symbol Glossary indirection symbol. One of the following: Symbol . (period) .EXT Declares ... • • • • An array or structure as having standard direct addressing A simple pointer or structure pointer An array or structure as having extended addressing An extended (32-bit) simple pointer or structure pointer .SG A standard (16-bit) system global pointer .SGX An extended (32-bit) system global pointer native.
release version update (RVU) Glossary release version update (RVU). A collection of compatible revisions of NonStop OS software products, identified by an RVU ID, and shipped and supported as a unit. An RVU consists of the object modules, supporting files, and documentation for the product revisions. An RVU also includes a set of documentation for the overall RVU. RISC. See reduced instruction set computing (RISC). RVU. See release version update (RVU). TAL. See HP Transaction Application Language (TAL).
TNS object file Glossary TNS object file. An object file created by a TNS compiler or the Binder. A TNS object file contains TNS instructions. TNS object files can be processed by the Accelerator or by the TNS Object Code Accelerator (OCA) to produce to produce accelerated object files. A TNS object file can be run on TNS, TNS/R, and TNS/E systems. TNS Object Code Accelerator (OCA). A program optimization tool that processes a TNS object file and produces an accelerated file for the TNS/E architecture.
TNS/R native mode Glossary TNS/R native mode. The primary execution environment on a TNS/R system, in which native-compiled MIPS object code executes, following TNS/R native-mode compiler conventions for data locations, addressing, stack frames, registers, and call linkage. Compare to TNS interpreted mode and TNS accelerated mode. See also TNS/E native mode. TNS/R native object code. The MIPS RISC instructions that result from processing program source code with a TNS/R native compiler.
word Glossary pTAL Guidelines for TAL Programmers —527256-002 Glossary- 6
Index Numbers 16-bit arithmetic 2-9 32-bit addresses 2-14 A Absolute addresses 2-20/2-23 Addition 2-9 Address types 2-11 Address variables 2-14 Addresses 32-bit 2-14 absolute 2-20/2-23 arithmetic using 2-16/2-17 comparing to addresses 2-19 to constants 2-19/2-20 converting 2-15/2-16 indivisibility of 2-20 integer expressions and 2-15 integer variables and 2-14 pointers and 2-10/2-24 Address-conversion routines 3-1/3-3 Address-type variables 3-4 Altering parameter masks 2-29 Arithmetic left shifts 2-56/2-57
H Index Functions RETURN statement and 2-32/2-33 returning a value from 2-32 returning from 3-27 H Hardware indicators 2-40/2-51 See also Condition codes I Incrementing pointers 2-17/2-18 Indexes, for stack marker access 2-26/2-27 Indirect pointers, equivalenced variables and 2-23/2-24 Indivisibility of addresses 2-20 Integer expressions, addresses and 2-15 Integer variables, addresses and 2-14 K Keywords in syntax diagrams xii L L register, saving 2-53 Labels using 2-24/2-35 @ operator and 2-25 Left
R Index Procedure pointer variables declaring 3-11/3-12 using 3-13 Procedure pointers generally 3-6 declaring generally 3-7/3-11 as formal parameters 3-17/3-18 as variables 3-11/3-12 in structure fields 3-14/3-16 Procedures calling dynamically 2-29, 2-33/2-35, 3-18/3-20 extensible 2-29 function 3-27 names of, @ operator and 2-25 using 2-24/2-35 variable 2-29 PROCPTR formal parameters declaring 3-17/3-18 @ operator and 2-39/2-40 pTAL characteristics of 1-1 compiling programs written in 1-2/1-3 reason for 1
U Index U Unsigned arithmetic operations 2-9 Unsupported TAL features of 1-6 USE statement 2-54 V Variable procedures 2-29 Variables address 2-14 address-type 3-4 equivalenced indirect pointers and 2-23/2-24 memory and 2-8 integer, addresses and 2-14 local, parameters and 2-38 procedure pointer See Procedure pointer variables referencing 2-6/2-8 @ operator and 2-13 Special Characters $CARRY routine 2-40 $OPTIONAL routine 2-30 $OVERFLOW routine 2-40 @ operator formal parameters and 2-39/2-40 labels and 2
