Beginning basics

Okay. You've finally gotten up the gumption to press that ol' New Macro button in the Connexion client. You've faced a barrage of windows demanding immediate responses (but, luckily, explaining themselves fairly well), and you've clicked the Edit button, so now you're looking at a screen containing only some odd words.

  ' MacroName: [the name you entered in the Macros window]
  ' MacroDescription: [the brief description you entered of what the macro does]
  sub main

  end sub

Quickie translation:

"MacroName" and "MacroDescription" are self-explanatory. You can change them all you want from this screen, but that won't have any impact on what displays elsewhere in Connexion (such as the Macro window or the Customize... window). There are other ways to change the name and description as they display elsewhere, so don't panic if you don't like what you typed!

"Sub main" and "end sub" are the core of the macro. They tell the computer that everything between those two commands is the heart of the program. In essence, when the macro runs, it starts at "sub main" and runs until it hits "end sub," at which point it stops.

The first character in each of the first two lines is also important to learn right off the bat. A "comment" (also called a "remark") is a note from the programmer to whomever reads the program next; everything following the comment mark on a line will be ignored by the computer when it runs the macro. The comment mark is the single quote mark ('), so be careful how you use it. Also, the verb phrase "to comment out" a line means "place a single quote at the beginning of" the line; you will often see this phrase in macros with instructions on how to customize them for your own uses.

There are three more lines that you should add to just about every macro you create; add them after the "MacroDescription" line and before the "sub main" line.

  'Macro Created By: [Your name]
  'Macro Last Updated On: [today's date]

  Option Explicit

The first two lines provide information that is useful for anyone else who happens to see your macros (which could be anyone who sees your macros on the Web, or your replacement if you retire)--or they may even be useful to you if you have to check on a macro a year after you forgot you wrote it!

The third line is a command with ramifications you'll learn more about later; all you need to know for now is that it will help you find any typos you might make in the macro.

Here's a little trick that will make your life a lot easier when writing macros.

  Dim CS as Object
  Set CS = CreateObject("Connex.Client")

Translation:

1) "Create a short-hand method of referring to an object, and use 'CS' as the short-hand for that."
2) "CS is short-hand for Connex.Client (basically the part of the Connexion program where the Connexion-specific macro commands are stored) for the purposes of having a macro run certain Connexion-specific commands."

Now, instead of typing out "Connex.Client" in commands like "Connex.Client.AddField" or "Connex.Client.RunMacro" (don't worry, I'll explain how those commands work in a minute), you only have to type "CS.AddField."

(Other than that, it's not all that important at this point that you understand exactly how these commands work, as long as you grasp the basic concept of creating the short-hand so that "CS" works with all of the Connexion-specific commands I'll be using in these lessons.)

Before I go on to CS.AddField (see how handy that CS shortcut is?), one brief but vitally important side note. The "Field" in this and other commands refers to an entire MARC field (such as the entire contents--including MARC tag--of the 245 line). This is very different from the way Passport and some other programs handle data, and bears a little explaining for those who are used to Passport macros. Passport operates as a "screen editor", and as such allows the cursor to be moved anywhere on the page, keeps track of where fields are split when they are too long to fit on a single line, and allows text to be freely entered anywhere. Connexion may seem to work similarly, but it internally treats each MARC tag as a single line, regardless of how long the line is. In other words, Passport divides the display into rows and columns, but Connexion technically only uses rows. Also, in Passport, lengthy MARC fields (such as contents notes) may take up several rows, but in Connexion, each MARC field is considered to be a single row, even if it appears as multiple lines on the screen.

As you might think from the name, CS.AddField means "Add a field to the active bibliographic record." Here is a simple macro that adds a 949 line to the end of the active bibliographic record:

  sub main
    dim CS as object
    set CS = CreateObject("Connex.Client")
    bool = CS.AddField(99, "949  Note goes here.")
  end sub

What this macro does is set up the "CS" shortcut and then insert a new 949 field after any existing 949 fields with the contents "949  Note goes here." (Note that there are no extra spaces between the tag and the indicators and between the indicators--which in this case are both spaces--and the field data.) If all goes well, then the "bool" variable will be TRUE (or 1), but if the line cannot be added for some reason, then the "bool" variable will be FALSE (or 0). (I'll explain more about variables and values in a later lesson.) Note that in OML, "TRUE" is normally defined simply as "not zero"; Connex.Client commands always use 1 for TRUE, but other OML commands may use -1 for TRUE.

I have a confession to make. The CS.AddField actually inserts that new 949 field after the first ninety-eight 949 fields; however, since there will likely be few or no 949 fields already in the record, using 99 has the same effect as "add this as the last of any 949 lines." If you want to be even more certain that a line will be the last instance of a field, you could use 999 instead. If you instead wanted to add a new 650 field that was always the second 650 field if any other 650 fields already existed in the record, you would use 2 instead of 99.

Another very useful command to know right away is CS.RunMacro, which--as you probably figured out--tells the computer to run another macro. The second part of the command is the macrobook which contains the macro, an exclamation point, and then the name of the macro to run; all enclosed in quotes with no spaces.

  sub main
    dim CS as object
    set CS = CreateObject("Connex.Client")
    bool = CS.RunMacro("MyMacros!Add949")
  end sub

In this case, the computer goes into the "MyMacros" macrobook and runs the "Add949" macro. This particular example is functionally the same (though slightly slower) as just running the Add949 macro itself. This may seem needlessly redundant right now, but with this command, you won't always have to completely duplicate macros when you have two macros that do very similar things. For example, you could have one macro that adds a 949 field, a second that adds a 910 field, and for those cases where you need both, a single macro that runs each of those in turn. More uses of CS.RunMacro may become evident as you write more--and longer--macros.

Next time, variables...