Chapter Contents

Previous

Next

transfer

Transfer Debugger/Program Values to CLIST/EXEC Variables

ABBREVIATION

tran{sfer}

FORMATS

Format 1:	transfer	VAR-NAME [FMT-SPEC] auto [KEYWORD]
Format 2:	transfer	VAR-NAME [FMT-SPEC] ENVIRONMENT [- N]
Format 3:	transfer	VAR-NAME [FMT-SPEC] value EXPRESSION
Format 4:	transfer	VAR-NAME str EXPRESSION [,N]
Format 5:	transfer	VAR-NAME dump EXPRESSION [,N]
Format 6:	transfer	VAR-NAME type of EXPRESSION
Format 7:	transfer	VAR-NAME cause
Format 8:	transfer	VAR-NAME scope

DESCRIPTION

The transfer command enables you to assign different character strings containing debugger information or program values to CLIST/EXEC variables. The transfer command facilitates communication between the debugger and CLISTs and EXECs. Note that transfer is issued to the debugger by a CLIST or EXEC, not from the Command window.

In all the formats above, VAR-NAME is any valid CLIST or EXEC variable name. VAR-NAME is limited to 64 characters. FMT-SPEC is a valid format, which means any valid printf specification, provided it begins with a %.

Format 1: Format 1 transfers one or more settings of the auto option. FMT-SPEC is specified only for the linesize keyword. If no keyword is specified, all auto settings are transferred in a string formatted as follows (where b=blank):

Columns	String
1-6	bbecho/noecho
7	blank
8-11	bbid/noid
12	blank
13-18	bblist/nolist
19	blank
20-28	bbnullptr/nonullptr
29	blank
30-35	bbwrap/nowrap
36	blank
37-45	bbcmacro/nocmacro
46	blank
47-55	bbdumpabs/nodumpabs
56	blank
57-66	bbexececho/noexececho
67	blank
68-76	bbextname/noextname
77	blank
78-82	bbcxx/nocxx
83	blank
84-95	LINESIZE:nnn

Individual settings are transferred by specifying the keyword.

Format 2: Format 2 transfers various ENVIRONMENT settings. The -N option is used to call ENVIRONMENT settings that are earlier in the calling sequence. For example, -1 can be used to transfer the value of a setting that is one function earlier in the calling sequence. The ENVIRONMENT settings that can be specified as arguments to the transfer command, include the following:

• the current address or any address (using the -N option) in the calling sequence. This version of Format 2 is

  transfer VAR-NAME [FMT-SPEC] address [-N]

  The formatted string contains the appropriate offset in hexadecimal format with a leading 0p , for example, 0p00123456 . At the return line-number hook, on the jumper's side of the longjmp function, an address is not available, and n/a is returned.

• the current section name (sname) or any section name (using the - N option) in the calling sequence. This version of Format 2 is

  transfer VAR-NAME sname [-N]

• the current function name (fname) or any function name (using the -N option) in the calling sequence. This version of Format 2 is

  transfer VAR-NAME fname [-N]

  This is similar to using sname. However, the string may contain leading blanks.

• the current line number or any line number (using the -N option). This version of Format 2 is

  transfer VAR-NAME [FMT-SPEC] lineno [-N]

  The formatted string contains the appropriate decimal line number at a line-number hook, for example, 234. At the prologue and epilogue hooks, calls, entry, or return is returned.

• the current offset or any offset (using the -N option). This version of Format 2 is

  transfer VAR-NAME [FMT-SPEC]offset [-N]

  The formatted string contains the specified offset in hex with a leading 0p , for example, 0p0002BE . At the return hook, an offset is not available, and n/a is returned.

Format 3: Format 3 assigns the value of an expression to a CLIST/EXEC variable. EXPRESSION is any valid scalar expression supported by the print command, and FMT-SPEC is any valid format specification supported by the print command.

If an FMT-SPEC is given, the string assigned to VAR-NAME is similar to that created for the print command, but without the expression : prefix. Strings can be transferred by specifying %s printf format specification, but using the str keyword may be more natural. (See Format 4, which is described next.)

If no FMT-SPEC is given, the default output is as follows:

Type 1

defaults to arithmetic.

short and long	the decimal value using the %d format for signed and %u for unsigned.
char	printable: x form escape character: \ n form otherwise: \ xnn
float	and double %.6E and %.15E, respectively.

Type 2

defaults to pointer. Eight hexadecimal digits are prefixed with a 0p .

Type 3

structure or union types are not allowed. Only scalar types are allowed.

Type 4

defaults to array. The address of the array is output using the format of Type 2.

Type 5

defaults to address. The address is output using the format of Type 2.

Type 6

defaults to enum . The enum constant is printed. If there is no enum constant corresponding to the value, the value in decimal is printed.

Type 7

defaults to bitfield. The %d or %u format is printed, depending on whether the bitfield is signed or unsigned.

Format 4: EXPRESSION is any valid expression accepted by the dump command, which is any address type expression. If the optional, N is not specified, a null-terminated string is copied to VAR-NAME. Otherwise, N bytes, followed by a null byte, are copied. The following examples illustrate this format. Assume a=abcdef .

transfer xyz str a (xyz gets the string "abcdef ")

transfer xyz str a,3 (xyz gets the string "abc")

Format 5: EXPRESSION is any valid expression accepted by the dump command, which is any address type expression. If the optional, N is not specified, the hex representation of a null-terminated string is copied to VAR-NAME. Otherwise, the hex representation of N bytes is copied. Again assuming a=abcdef" , the following examples illustrate this format:

transfer xyz dump a (xyz gets the string & "818283848586")

transfer xyz dump a,3 (xyz gets the string "818283")

Format 6: Format 6 assigns the type of an expression to a CLIST/EXEC variable. The string assigned to VAR-NAME is a string that describes the expression in C terms. Assume i , cp , and sp are declared as follows:

   int i;
   char * cp;
   struct SSS * sp;

Then, this format is illustrated as follows:

transfer xyz typeof i(xyz gets the string "int")

transfer xyz typeof cp(xyz gets the string "char *")

transfer xyz typeof sp (xyz gets the string "struct SSS *")}

Format 7: Format 7 uses the VAR-NAME argument to assign the reason the debugger has control to a CLIST/EXEC variable. VAR-NAME is assigned one of the following strings:

	NNNN REASON FNAME (SNAME) LINE-SPEC
	NNNN monitor MON-DET
	0000 signal SIGNAL-NAME
	0000 attn

NNNN is the request number in the query list, and it is right-justified with as few digits as needed. The REASON argument is either break, step, or continue. FNAME and SNAME are the function name and compilation of the routine that was stopped in. LINE-SPEC is a line number (in decimal) or calls/entry/return.

MON-DET is what appears for that monitor if you do a query.

If more than one of the above causes is present, the following hierarchy (in order of most important to least important) is used to output the more important cause:

	TERMIN
	TERMOUT
	SIGNAL
	ATTN
	MONITOR
	BREAK (also generated for on commands)
	RUNTO
	CONT
	STEP

Format 8: This format uses the scope keyword to transfer the traceback level from the debugger to a CLIST or EXEC variable specified by the VAR-NAME argument. The output from the command is a string containing the traceback level and starting with a minus sign. For example, if the traceback level is five, the output of the command is -5.

EXAMPLES

The EXEC named DUMPTREE, in Example REXX EXEC Application, contains several transfer commands that demonstrate how you can transfer debugger variable values to CLIST or EXEC variables.

SYSTEM DEPENDENCIES

none

SCOPE

In an expression context, the transfer command uses command scope to resolve references to all identifiers.

RETURN CODES SET

• Successful: 0

• Unsuccessful: 1

Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.