Commands
Heel! Sit! Fetch! Those are three commands you are used to giving (or trying to give) your dog. The computer works in similar ways--except that instead of those particular words, it listens to CS.MoveCursor, CS.Wait, and CS.GetTextInRegion. Also like a dog, if you give the computer a command it doesn't understand, it will sit there and do its best impression of a quizzical look, much to the aggravation of the person giving the commands.
You've already been introduced to a few commands in earlier lessons-- variable definitions, RunMacro, and CS.PutText among them. Let's start with a simple macro:
sub main
CurrentSession.PutText "PDN", 1, 1
RunMacro "PRSMUTIL!SendCommand"
end sub
Recap: What this does is take the three letters "PDN", move the cursor to the home position (upper left corner--row 1, column 1), put the text onto the screen starting at that point, then running the OCLC SendCommand macro (more commonly known as Passport for DOS's F11).
Many commands, CS.PutText among them, allow you to substitute variables for certain sections of the the command. Any command that needs a whole number or some text can use an Integer variable or a String variable; it's only a matter of replacing the numeric constants (such as 1) and string constants (such as "PDN") with numeric variables and string variables. For example, another way of achieving an identical via with a somewhat different method is to do this:
sub main
a$ = "PDN"
x = 1
CurrentSession.PutText a$, x, x
MBook$ = "PRSMUTIL"
MName$ = "SendCommand"
FullmacroName$ = MBook$ + "!" + MName$
RunMacro FullMacroName$
end sub
In this particular example, it's much easier to just use the former method. However, there are times when knowing how to do the latter may come in very handy.
Another handy command to know is Chr or Chr$ (the "$" is optional in OML). This command takes any decimal number between 0 and 255 and converts it into a single character of text. (The number is called the ASCII code for the character; in this case, a decimal representation of every character.) This is generally not necessary for normal letters, numbers, and punctuation found on every keyboard (those characters between 32 and 127), but can be a lifesaver when trying to use characters that can't be typed normally into a string--such as the Enter key, the Backspace key, and all of OCLC's ALA diacritic characters. For example, Chr(13) + Chr(10) is the character combination (Carriage Return + Line Feed) that wraps long lines in PRISM, and Chr(223) is another way of representing OCLC's field delimiter character.
Please note that if Chr is used to add a special character to a string that will be used by a command which requires "normalized data" (another way of using standard characters to represent non-standard characters), things may not work the way you expect. More on normalized data at a later time.
Ever wanted to pop up a window with a message for the user (such as "Macro has finished") and an "Ok" Button, but couldn't figure out the Dialog Box commands? If that's all you need it to do, there's an easy method to do just that--the Message Box.
MsgBox "Hello World"
As you can see, in it's basic form the command is fairly straightforward; all you need to supply is the text to be displayed, and the computer takes care of the rest. If you use variable strings instead of a string constant (that is, instead of plain text in quotes), things can get quite interesting:
sub main
a$ = "Hello"
b$ = " World"
c$ = " Cup Soccer"
d$ = ", I must be going"
e$ = a$ + b$
MsgBox a$ & b$
MsgBox e$
MsgBox a$ & " Dolly"
MsgBox b$ & c$
MsgBox a$ & d$
end sub
As you can see, there's a slight difference in syntax between simply adding strings and including multiple strings in a MsgBox statement--one looks for "+" and the other looks for "&".
After a while, you may find the command CS.GetTextInRegion to be worth its weight in gold. More than that, acually, since it doesn't weigh all that much. You will usually see the command in the form:
CS.GetTextInRegion Text$, 2, 5, 4, 20
The way it works is this: The command looks at the current screen, finds a start point, finds an end point, gets all the text in that area, and stores it in Text$. The first two numbers are the row and column of the start point, and the last two are the row and column of the end point. So, if the first line of your screen was the following:
> P CAT SID: 01234 OL
and you wanted a macro to look at those last two letters (which in this case are the 31st and 32nd characters), you would use this:
CS.GetTextInRegion Text$, 1, 31, 1, 32
When the command is done, Text$ will equal whatever characters are #31 and #32 in the first row; in this case, Text$ will equal "OL". If the last two letters were not "OL" but rather "AF", Text$ would equal "AF".
If you want the macro to take a quick breather and pause a few seconds, then you need look no further than CS.Wait.
CS.Wait 4
This pauses the macro for 4 seconds. Simple, eh? However, if you want the macro to wait for a certain word to be displayed on the screen, then the way to do that is this:
CS.Receive 5, "Logon:"
This command will pause the macro for up to 5 seconds while it waits for the specified characters to be sent from the other end of the connection you are on and received by your computer. Once the text is received, it goes on to the next command, whether or not the 5 seconds are up. Be warned, however, that if it doesn't receive the specified text string in the specified time, it causes an error to occur! Be careful that the time you specify is long enough to cover a slow connection, but short enough that you're not left twiddling your thumbs for the macro to time out if the text you were waiting for doesn't actually show up but the system is running smoothly and correctly.
Using some of what you've learned, you can now write a macro that can export a record, save it, then display the save file number in a message box. I'll include remark statements explaining each section so you can easily follow what's going on in each block of statements.
sub main
'Set up CS as short-hand for CurrentSession
Dim CS as Session
Set CS = CurrentSession
'Use a string so as to avoid typing the same thing over and over later
SendCom$ = "PRSMUTIL!SendCommand"
'Type "xpo" at the home position and send it as a command
CS.PutText "xpo", 1, 1
RunMacro SendCom$
'Wait for OCLC to return the message "Record exported in USMARC."
CS.Receive 5, "USMARC"
'Type "s" at the home position and send it as a command
CS.PutText "s", 1, 1
RunMacro SendCom$
'Wait for the screen to shift after saving the record
CS.Receive 5, "saved"
'Get the save file number from the screen--row 2, col's 34, 35, 36, 37
CS.GetTextInRegion SaveNum$, 2, 34, 2, 37
'Display the number in a message box
MsgBox SaveNum$
end sub
Pretty amazing!
Next time, string manipulation...