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.GetActiveRecord, CS.SaveRecord, and CS.GetFieldData. 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, CS.GetActiveRecord, and CS.AddField among them. Let's start with a simple macro:
sub main
Dim CS as Object
Set CS = CreateObject("CatME.Application")
CS.GetActiveRecord
bool = CS.AddField(99, "949 Some note here.")
end sub
Recap: What this does is set up the "CS" shortcut, verify that there is an open record to act upon, and then add a field to the end of that record with the contents "949 Some note here.")
Many commands, CS.AddField 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 "949 Some note here") 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
Dim CS as Object
Set CS = CreateObject("CatME.Application")
x = 99
TagName$ = "949"
FieldContents$ = "Some note here."
FullField$ = TagName$ + " " + FieldContents$
CS.GetActiveRecord
bool = CS.AddField(x, FullField$)
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.
If you want text to appear at the cursor's current position, regardless of where on the screen that may be, the command to use is SendKeys. (This is because, unlike Passport, CatME is totally blind to the cursor and can normally only act on a specified field regardless of whether or not the cursor is at that field.) SendKeys sends text to Windows (and thus CatME, since it will be the "active" program) as if it were typed by the user, including "command" keystrokes such as Alt-H.
sub main
SendKeys "Juvenile literature."
end sub
This example sends "Juvenile literature" as if the user typed it; it will appear on screen wherever the cursor is.
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 separates one MARC field from the next, 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.
Also note that the field delimiter character will not be inserted when you want a macro to add text using SendKeys. (It will correctly be inserted when you use CS.AddField and similar commands, however.) If you have to use SendKeys, a workaround to this is to use the following string to insert a delimiter character at the current cursor position:
SendKeys "%eeasss%c"
This can be combined with other SendKeys text, as follows:
sub main
SendKeys "%eeasss%cv Juvenile literature."
end sub
The above macro will insert "$v Juvenile literature." at the cursor's
current position. This situation is also true for all diacritics; the
above method can be made to work for any of them--just go to the ALA
Character Entry window, then to the ALA Character Name box, and type the
first letter of the name of the character until it appears in the
box; then replace "sss" with the letters you typed. For example, an
umlaut could be represented as
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
After a while, you may find the command CS.GetFieldData 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:
bool = CS.GetFieldData(4, Text$)
The way it works is this: The command looks at the current screen, finds the specified line, gets all the text in that line, and stores it in Text$. It is important to note that CS.GetFieldData always includes the Start-of-Message character that begins each line.
CS.SetFieldData works in the reverse; and whereas CS.AddField is an "insert" command, CS.SetFieldData is an "overstrike" command.
bool = CS.SetFieldData(4, Text$)
This macro fragment replaces the fourth line of the record with the contents of Text$. You must include the tag number and spaces or indicators, but you do not have to include the Start-of-Message character if you do not want to; CatME will automatically make sure it is there.
If you want to delete a line, and know the line number, use CS.DeleteField. The following example deletes the sixth line of the record, and shows how to use a variable to do so.
linenum% = 6 bool = CS.DeleteField(linenum%)
Many of OCLC's commands can be automated with macros; these commands take the form of bool = CS.<command>. Examples of this include:
bool = CS.Validate bool = CS.UpdateHoldings bool = CS.DeleteHoldings bool = CS.Produce bool = CS.AddOnlineSaveFile bool = CS.Export bool = CS.Print bool = CS.Reformat bool = CS.SaveRecord
Using some of what you've learned, you can now write a macro that can add a field, alter the added field, display the old and new lines in a message box, then export and save the file.
sub main
'Set up CS shortcut
Dim CS As Object
Set CS = CreateObject("CatME.Application")
'Verify that there is an active record in the display
CS.GetActiveRecord
'Add a new line 6 to the record
bool = CS.AddField(6, "049 ABCD")
'Get the contents of line 6
bool = CS.GetFieldData(6, OldField$)
'Set up the new field
NewField$ = "049 DCBA"
'Put the new field into the record
bool = CS.SetFieldData(6, NewField$)
'Display the results in a message box
MsgBox OldField$ + Chr(10) + "was replaced with" + Chr(10) + NewField$
'Export the record
bool = CS.Export
'Save the record in the local bibliographic file
bool = CS.SaveRecord
end sub
Pretty amazing!
Next time, string manipulation...