ArborX

getvar

Longname: get var iable   Open the Documentation Legend
Released: not available 
Created: not available 
Last modified: 6.78a 

Summary
 The getvar macro allows you to extract system information from 3B2 about the user's setup. This information can be utilised in many stituations for example; assessing the state of the current document, values of items currently in format, or results of conditional formatting tests.
Example extract

The getvar code for the 'current text stream name' is 11520. The syntax shown below gets the current text stream name and places it in a variable called ^name:

 getvar 11520,"name"

Syntax (SVNNA)
getvar (  data type:n how many:n data group:n item number:n string number:n  )  variable:s?
data type:n The first digit of a getvar code defines the type of data that will be retrieved by getvar. The currently defined types are:
data type:n
0  A word. A value in the range -32768...32767.
data type:n
1  A string. A character string such as a filename.
data type:n
2  A length or size. A value or size in the range 2147483647... 2147483648. Sizes are retrieved in units of 0.0001mm. (see deci-microns with ^)
data type:n
3  A string. Up to 80 characters from a numbered string in one of 3B2's strings files or a string defined with defstr or addstr. This data type is always followed by a how many of 1, and then by a string number, e.g. 31086 to get the 3B2 version number from string no.86. The data group and item number are not used.
how many:n

The second digit of a getvar code tells 3B2 how many values to get. The first value is that of the code listed in the macro. The second and subsequent values are those of the next consecutively numbered items in the list of getvar codes.

1..9  You can get up to 9 variables using a single getvar macro provided they belong to the same group (i.e. have a common third digit) and are consecutively numbered. In the list of getvar codes the second digit is always 1. If you need to get more than one value, change this to 2 or more (up to 9).
data group:n 3B2 getvar codes are organised in five groups, each of which can contain up to 100 items numbered from 0 to 99. With data types 0..2 the third digit of a getvar code simply tells 3B2 which group to look at.
item number:n The last 2 digits of a getvar code specify a precise item number that identifies the data retrieved by getvar. Item numbers are allocated by Advent arbitrarily, but related items are kept together so that they can be retrieved with a single getvar command (see how many). Not all item numbers are used - gaps in the numbering are left for future expansion.
string number:n A three digit number representing a numbered string in one of 3B2's strings files or a string defined with defstr or addstr.
variable:s The name(s) of one or more variable(s) which you wish to store this information in. The variable names which store the requested values have to appear inside double quotes, but do not have the leading ^ symbol.

Macros, scripts and show strings often require information about a user's setup and document settings. This can include items such as the size of the screen, colour settings and zoom level, current font selections, etc.

In most scripts using wdb is far simpler, although using getvar gives your script access to a number of items for which dialogue boxes do not exist, such as a user's command-line parameters, screen pixel width and height, mouse position etc. It is also not sensitive to the order in which dialogue boxes are constructed.

The getvar code, a sequence of five digits used by 3B2 to identify setup and document-specific items (system variables). Each getvar code consists of a sequence of digits which represent four specific components:
 data_type: n how_many: n data_group: n item_no: n 5
 data_type: n how_many: n string_no: n 7

You should, however, be able to use the list of getvar codes without being too concerned about what each of the digits stands for. A full list of 3B2 getvar codes can be accessed through any of the show strings dialogue boxes, or with the macro wmn 800 pre 3B2 V7 and wmnx 800 post 3B2 V7. A full list is also available in the System Variables_en section.
Example

The getvar codes for the size of the current text stream and the cursor position in the current text stream are 21521 and 21522 respectively. The macro shown below gets these variables and places them in two variables called ^s and ^p.

 getvar 22521,"s","p"
It is worth remembering that show strings can be used to display the first 79 characters of a numbered string, e.g. <?show $31005v> would display the first 79 characters of string no.5 ('{manuals}clip') on the page. This feature can be quite useful if you are using defstr or addstr to define a string and want to check on how the string is being written.
Example

You can also use getvar to insert variable text in your text stream. The diagnstc.3d file supplied with Arbortext APP is a good example of a text composed almost entirely of show strings using getvar codes. The example below inserts the current filename into your text stream:

 tshow "$11500v"

Document created on 08-Feb-2003 (revision 1)