The &GET String Function The &GET String Function

When writing macros for MOSES, it is often desirable to prompt the user for information. This can be accomplished by using the string function:


     &GET(WAY, DATA )

This string function returns a string, and here WAY is the manner in which the response is obtained and DATA is the other information necessary to make the request. WAY must be either FILE, RESPONSE, YES/NO, PICK, N_PICK, GET_LIST, or GET_NAME and DATA depends upon WAY. The details of how the information is requested depend on the current user interface. For a terminal interface, it is all done with text and typing. With a window interface, different dialog boxes appear.

The first three types of WAY request for a file name, a general string input, and a YES or NO response respectively. Here, DATA is simply a description of the data requested. For example,

     &INSERT &GET(FILE Select your MOSES custom file)

and

     &INSERT &GET(RESPONSE Input your MOSES custom file name)

will both return a string, but the first will pop up a file selection box and allow the user to browse and click on the desired file. The second will pop up an input box and the string returned may or may not be a valid file name. YES/NO places DATA in a box with YES and NO buttons and returns either YES or NO depending on which button is pushed.

The last four types of WAY pop up a list and the user is allowed to pick from the list. For PICK the form of DATA is:

     MAX_PICK, TITLE, ITEM(1), ITEM(2), ....

Here MAX_PICK is the maximum number of items which can be chosen, TITLE is the title of the dialog box, and ITEM(i) are the items which can be chosen. If more than one item is chosen the string will be composed of the name of each item chosen.

The type of WAY of N_PICK stands for "name pick" and here the form of DATA is:

     MAX_TO_PICK, TYPE_OF_NAME, TITLE

Here TYPE_OF_NAME is a valid value of the &NAMES command (issue the command &NAME NAMES to see what is available or see the documentation for &NAMES), TITLE is again the title of the pick box, and MAX_TO_PICK is the maximum number of items which may be chosen. With this type, the list depends on the current state of MOSES, in that the list is obtained from the current database. This removes the macro writer from having to know the state. As an example, consider

     &REP_SELECT -BODY &GET(N_PICK 1 BODIES 'Select A Body')

which will present the user with a list of the bodies defined and ask him to select one.

The last two types of WAY GET_LIST and GET_NAME have a form of DATA exactly the same as PICK and N_PICK respectively. The difference is that with these types, a combination EDIT/PICK box is popped up. Here one can type data into the edit box or select from the available list, or do both.