Archive

Archive for the ‘Coding’ Category

A Matter of Style – Labels…

November 9, 2017 Leave a comment

As much as possible I try to make it obvious from a variable label, what type of variable it is and wherever possible, what other variable or control block it is related to.

Constants

I start variable names for constants with a # sign, thus:

#NAME DC C'NAME'

If a variable starting with a # sign is on the receiving end of an instruction, it is wrong because I should not be modifying constants!

Equates

I start equated value names with an @ sign, thus:

@ONE   EQU   1
@FLAG1 EQU   X'80'

For equated symbols that define a length, I add the suffix ‘_LEN’ to the symbol name, thus:

FIELD1      DS    CL8
@FIELD1_LEN EQU   *-FIELD1

That way, it is obvious in the code that I am referring to an equated length value, for example:

          LA    R1,@FIELD1_LEN        Get field length in R1

It it obvious that I intend to load the field length and not the field address into the register but having the _LEN suffix ensures that I get the length and do not accidentally code the field address instead.

Equate/Field relationship

I prefer to ‘tie’ equated values for a field to the field they relate to by using a naming convention that uses the field name as part of the equate symbol, thus:

FIELD1         DS  C
@FIELD1_YES    EQU C'Y'
@FIELD1_NO     EQU C'N'
@FIELD1_NOTSET EQU X'00'

Then in code I would write something like this:

          CLI   FIELD1,@FIELD1_YES
          BE   DO_YES
          CLI   FIELD1,@FIELD1_NO
          BE   DO_NO
          B     NOT_SET

 

Similar code would apply to setting the field value, only use equated symbols that are related to the target field. This convention ensures that you are only setting and testing for values actually defined for the field.

About the only exception to this rule that I use is the use of the following common equated symbols:

@YES    EQU   C'Y'
@NO     EQU   C'N'
@POSTED EQU   X'40'

@YES and @NO should be obvious, @POSTED is to test an ECB posted bit flag,E.G:

          TM    ECB1,@POSTED           Is ECB posted?
          BO    DONE

 

Field/DSECT relationship

When I am creating my own DSECTS I prefer to prefix the name of each field within the DSECT with the DSECT name and an underscore, thus:

SOMEBLOK DSECT
SOMEBLOK_FIELD1 DS CL8
SOMEBLOK_FIELD2 DS F
@SOMEBLOK_LEN   EQU *-SOMEBLOK

Using this standard makes it easy when reading source code to determine who owns a field. There is no confusion. The length equate for the control block also follows my convention of adding _LEN to the end and prefixing the equate symbol with an @ sign to avoid ambiguity in the executable code.

The exception to the rule…

I do allow for one exception to this rule though and that is for a program’s working storage. Typically I prefix working storage fields with the prefix STG_ (short for ‘storage’) although you can use anything you want, to identify working storage fields, for example W_ etc. It is preferable to use the underscore as part of the name to avoid situations where a field name ‘might’ happen to start with whatever prefix you are using. For example if you use just W as your working storage field prefix, is WORKF1 a field in your working storage or somewhere else? Using this convention, STG_WORKF1 or W_WORKF1 are obviously part of the code’s working storage. And again, the convention ensures that you are using the field you intend and not a WORK1 field defined somewhere else that might allow the program to assemble but my then fail at execution time because the storage it refers to is not addressable or it is addressable but it’s the wrong field and messes up some other code (good luck finding that one!).

Summary

Whatever conventions you use, the aim is to make it less likely to introduce errors when developing the code and to make it much easier to read, and locate field owners several months later when someone else has to try to follow, understand and debug or modify your code.

 

 

 

 

Advertisements
Categories: Coding, Style

A Matter of Style…

November 9, 2017 Leave a comment

There are probably as many ways to write a program as there are programmers in the world, more if you accept that a program is solution or part thereof, to a problem and could be written in more than one language, each of which causes the writer to adopt differing styles.

So basically, there’s more than one way to skin a cat!

Now I’m not saying that the style of assembler programming that I have developed over the years is the best but I think it satisfies many of the requirements that I will cover in what I hope will be a short series of articles. Let’s put it this way, unless someone tells me different, I’ll tend to try to influence any code that I work in towards my preferred style although there are reasons for NOT doing that, for example to maintain the existing style or coding standards since a mix can make things worse.

SO! Why is style important?

Sometimes it isn’t. You may need to write a quick, one off, one use program to solve a problem. As long as it does the job, does style really matter? Well, it depends. If the code is simple then probably not but what if the code is complex? Then making the code at least readable and logical makes sense since if you get it wrong the first time through, it will be a lot easier to diagnose the problem and correct the code.

But let’s consider the more common situation where you are developing a program or even multiple programs that form a piece of software and those programs are for use by paying customers. In other words you are creating commercial software. I am also including software written for in house use (in the business sense) because such development, use and support usually involves internal billing and thus still qualifies it as commercial software.

Basically, if someone else other than the developer or developing department uses it, you can consider it to be commercial software in my mind.

So let’s say that you are assigned the task of developing a z/OS super widget application which, because it uses lots of system services will be written in assembler, or at least a lot of it will be. Let’s looks at how programming style will affect it’s life cycle.

Development

The faster you can develop and test the code to the point where it does what the requirements require without failing or causing other problems, the faster the product will reach the market and thus generate revenue for the business.

Everyone probably has a standard program entry and exit macro and possibly similar ones for subroutine entry and exit but what about other stuff. Parsing of input for example? Do you do it with hard coded assembler or use a macro or service to do parsing in a standard and consistent manner? If a service, do you call that service using a macro to make coding the call simpler and standard? Or, do you let your programmers set everything up by hand (guess which is the more reliable method)?

Do you use a standard form of label name for program labels and subroutine names? Are you still stuck in the ‘all labels must be 8 characters long’ mental state or do you use longer and more meaningful names, either CamelCase or with parts separated by underscores, E.G. WORK_FIELD_1.

Do you use naming standards to tie equated symbols to the field they relate to or is it a free for all. Is it easy to tell, without looking at the variable definition,  if a variable name is a label or an equated value and if a label, is it easy to tell which control block it belongs to, or if a constant, is it easy to tell that it is a constant?

And most importantly in my mind, do you create comment blocks for the program as a whole and for each subroutine that describes the program, it’s inputs, outputs and return codes and the same for all subroutines? Also, if the program is reliant upon a particular control block structure, do you document that WITHIN the code as best you can (using good old EBCDIC character graphics if need be) so that the architecture is right there in the code, not lost on some hard drive somewhere that got wiped because someone didn’t realize that what was on it was needed (the ‘not my job’ syndrome!).

Maintenance

If the code is well structured, follows consistent  naming standards, uses macros to standardize the coding of interface, has proper comments describing what each routine does, what it’s input and outputs are then understanding the code and diagnosing a problem becomes a lot easier and more importantly faster. You are also more likely to be able to correctly fix any problem without introducing new problems. All the above result in a faster turn around time for the resolution of any code related problems. They also mean it is much easier for someone other than the original developer to pick up the code and work on it with confidence.

This all results in improved customer confidence in the product and better tolerance for any problems that do occur because they know that they can be quickly resolved.

New Features

Code that is well structured is much easier to modify to add new features to. And just like the maintenance situation, there is less likelihood of such changes introducing new problems into either the new or the existing code. This all helps to get the product out to market that much quicker and earning revenue.

The Bottom Line

If you are a commercial programmer, that is, it’s your job, your work earns the business that you work for, the money that pays your wages. The quicker you can develop new code or fix existing code directly affects the companies business results and therefore your earnings.

 

 

 

 

Categories: Coding, Style

Conditional Assembly Language…

May 10, 2016 Leave a comment

If you’ve ever read or written a macro you have no doubt at least seen conditional assembly language. It’s all that AIF and AGO stuff that forms a sort of ‘program’ within the macro so that it can generate code or whatever depending on whatever the input parameters are.

What’s really cool though is that it is not just limited to macros, you can use it within open code as well. So you might ask ‘why would you need to do that?’ but even if you don’t ask, here’s one interesting situation that came up recently.

I had some code that used a macro to generate a DSECT to map a control block. However we were switching version of the product that supplied the macro and a field within the macro had changed names even though it’s content had not. The result was that my code would only assemble with one version of the macro since with the other one it would get a not found error for the changed label. Since I did not want to have to co-ordinate my source code change with a build tool change the problem I had was how to make my source code support both versions of the macro and DSECT that it generated?

In case you have not guessed, the answer is conditional assembly language.

Here’s an example.

The old macro/DSECT:

         MYMACRO
SOMENAME DSECT
MYFIELD  DS    CL8

The new version of the macro/DSECT

        MYMACRO
SOMENAME DSECT
NEWNAME  DS    CL8

 

 

So my code originally looked something like this:

         USING SOMENAME,R2
         CLC   MYFIELD,=CL8'AAAAAAAA'

Obviously if I switch to the new macro library, my assembly will fail since the field ‘MYFIELD’ is no longer defined within the DSECT.

However, what you can do is to test to see if the variable ‘MYFIELD’ is defined and if not then conditionally change the code that gets assembled. Thus:

         USING SOMENAME,R2
         AIF   (T'MYFIELD EQ 'U').NEWMAC
         CLC   MYFIELD,=CL8'AAAAAAAA'
         AGO   .CONT
.NEWMAC  ANOP
         CLC   NEWNAME,=CL8'AAAAAAAA'
.CONT    ANOP

 

The AIF tests to see if the ‘type’ specification for the field MYFIELD is ‘U’, that is undefined. If it is undefined that means it has not been seen by the assembler (yet) so jump to the label .NEWMAC and continue to generate the code from there, which of course generates the code using the new field label of NEWNAME.

If the field MYFIELD is not ‘undefined’ then the assembler generates the code using the old field name, MYFIELD and then jumps (AGO) to the label .CONT to continue the assembly.

As a result, no matter which version of the macro library I am using, my code still assembles and works correctly.

There are other ways of achieving the same effect; For example by using the conditional assembly language to control the redefining of the old or renamed symbol to a common name and using that common name in the open code.

One gotcha though to be aware of. The macro/DSECT has to be defined in the source code BEFORE the conditional assembly code. If it is defined after the conditional code then, since the assembler has not seen either field at the time it encounters the test for the field being defined, it will always treat it as being undefined which would cause an assembly error when using the old macro/DSECT library because it would generate the code to use the new field name.

Categories: Coding, Mainframe

When projects collide…

September 12, 2013 Leave a comment

The iPhone/iPad app I am developing is for live music use (not giving away any details just yet since I am sure any reasonable iPhone developer could knock up the same app in a couple of days and beat me to the finish line!) which means your hands are not so free. My original idea was to use a blue tooth connected foot pedal that I already happen to have (Airturn BT-105) to control the app. However it occurred to me that it would be pretty simple to add a blue tooth shield to an Arduino, hook up a few switches and make my own blue tooth enabled stomp box to control my app, plus I could have more than the two switches my current pedal has.

So, once the current Arduino project is done I’ll be starting on creating a blue tooth enabled stomp pedal to control this app and looking at blue tooth enabling my app to work with my custom pedal.

Categories: Coding, iPhone, xcode Tags: , , ,

Back to the iPhone project

September 11, 2013 Leave a comment

The Arduino project is on hold because I am waiting for parts to arrive which appear to be on a VERY slow boat from Thailand so I decided to get back to my iPhone project.

My iPhone app (which will be mainly an iPad app when it is done) currently has three view controllers. I guess you can think of these as logical screens. Each one has it’s own implementation file (class) and when I originally wrote things, just to get it all going I used a lot of global variables to share data between the view controllers. This got messy really quickly so I’ve been reworking the code over the past couple of weeks to get rid of the global variables and pass data between the view controllers the ‘proper’ way.

I also need to make the app support device rotation as well as both iPhone and iPad devices so for no particular reason I chose to attack the device rotation topic first. So far it is proving to be an interesting challenge to make all my view controllers  work correctly since only the currently displayed VC receives the orientation change messages so any hidden VC has to check the orientation when it is redisplayed and reconfigure the screen to match the current orientation. Let’s just say that this part of the project is still a ‘work in progress’!

I have managed to sketch out what I want the main interface to look like but all the current work is just to get to the point where I can actually implement the main app function and has nothing to do with the actual ‘guts’ of the app.

Oh, and now we have new devices (no doubt with new physical screen sizes) and a new OS to contend with as well.

Still, it keeps me off the streets at night!

Categories: Coding, iPhone Tags: , ,

Finished Code…

August 21, 2013 Leave a comment

This is the finished code for the Arduino project. I switched the code to use exclusive ORs to flip the settings and added a second switch detection block of code for the second switch. All in all, pretty easy.

I’m still waiting for some parts to arrive before I can construct the finished project but I don’t anticipate any problems other than it not physically fitting in the project box I have ordered!

#include <Bounce.h>

/*
Arduino Uno based stomp box Midi controller for T.C. Electronics M300
Copyright David E. Ellis 2013

Switch one toggle patches 2 and 3
Switch 2 toggles dry and mixed signal

 */

#define PATCH_SWITCH 4            // Pin 4 - Controls patch switch
#define BYPASS_SWITCH 5           // Pin 5 - Controls bypass (wet/dry)
#define PATCH_LED 12              // On=initial patch, off=alternate patch
#define BYPASS_LED 11             // on=bypass on (dry), off=bypass off (wet)
#define INITIAL_PATCH 2
#define ALT_PATCH 3
#define WET 0                     // Hear effect (wet signal) when bypass is off
#define DRY 127                     // dry signal when bypass on

// patch control
byte cur_patch = INITIAL_PATCH;
byte old_patch = ALT_PATCH;
byte cur_patch_led = HIGH;                            // high = led on
byte old_patch_led = LOW;

// bypass control
byte cur_bypass = DRY;                                // initial state for bypass signal is on (dry signal)
byte old_bypass = WET; 
byte cur_bypass_led = HIGH;
byte old_bypass_led = LOW;

Bounce bouncer1 = Bounce(PATCH_SWITCH,5);            // setup 5 ms debounce on switch 1
Bounce bouncer2 = Bounce(BYPASS_SWITCH,5);            // ditto on on switch 2

// the setup routine runs once when you press reset:
void setup() {   
  Serial.begin(31250);                              // Set MIDI baud rate:
  selectPatch(INITIAL_PATCH);                       // Set inital patch number
  setBypass(DRY);                                   // Set bypass to on initially (dry signal)
  pinMode(PATCH_SWITCH,INPUT_PULLUP);                // Open switch is normally pulled high
  pinMode(BYPASS_SWITCH,INPUT_PULLUP);                // Open switch is normally pulled high
  pinMode(PATCH_LED, OUTPUT);                         // initialize the led pin as an output.
  digitalWrite(PATCH_LED, cur_patch_led);              // set to current state 
  pinMode(BYPASS_LED, OUTPUT);                         // initialize the led pin as an output.
  digitalWrite(BYPASS_LED, cur_bypass_led);         // set to current state
}

// the loop routine runs over and over again forever:
void loop() {

  // Switch 1 controls the patch
  if (bouncer1.update()) {                           // returns true if switch state changed (on or off)
    if (!bouncer1.read()) {                          // if switch is pressed (input low)
      cur_patch=cur_patch^old_patch;                 // swap patch
      old_patch=old_patch^cur_patch;
      cur_patch=cur_patch^old_patch;
      selectPatch(cur_patch);                        // send it
      cur_patch_led=cur_patch_led^old_patch_led;    // swap led status
      old_patch_led=old_patch_led^cur_patch_led;
      cur_patch_led=cur_patch_led^old_patch_led;
      digitalWrite(PATCH_LED,cur_patch_led);        // send it
    }
  }

  // Switch 2 controls bypass (wet/dry mix)
  if (bouncer2.update()) {                           // returns true if switch state changed (on or off)
    if (!bouncer2.read()) {                          // if switch is pressed (input low)
      cur_bypass=cur_bypass^old_bypass;              // swap bypass state
      old_bypass=old_bypass^cur_bypass;
      cur_bypass=cur_bypass^old_bypass;
      setBypass(cur_bypass);                           // and set new state
      cur_bypass_led=cur_bypass_led^old_bypass_led;     // swap led status
      old_bypass_led=old_bypass_led^cur_bypass_led;
      cur_bypass_led=cur_bypass_led^old_bypass_led;
      digitalWrite(BYPASS_LED, cur_bypass_led);         // and send it
      }      
    }
  }  

void selectPatch(byte patchNum) {
  Serial.write(0xC0);                    // change patch command
  Serial.write(patchNum-1);              // patch '1' is really zero etc
}

void setBypass(byte mix) {
  Serial.write(0xB0);                    // CC
  Serial.write(0x51);                    // 81 - Bypass
  Serial.write(mix);                     // by on (127/dry) or off (0/wet)   
}
Categories: Coding, Development Tools Tags:

As if I don’t have enough projects….

August 14, 2013 Leave a comment

I’ve been playing around with an Arduino micro processor to build a small midi foot controller/stomp box for an effects unit in my synth rack unit. I just need it to be able to make the effects unit flip flop between two patches and also switch from a dry to a mixed signal.

This is the circuit for my prototype (just one switch so far to switch the patches):

ArduinoMidiSwitchCircuitAnd this is the code (oh look, more C!):

#include <Bounce.h>

/*
Midi controller for M300
Switch one toggle patches 2 and 3
Switch 2 toggles dry and mixed signal
 */

#define SWITCH1 4           // header P4, pin 3 - Controls patch switch
#define LED 13              // on board led on pin 13
#define INITIAL_PATCH 2
#define ALT_PATCH 3

  int patch = INITIAL_PATCH;

Bounce bouncer1 = Bounce(SWITCH1,5);    // setup 5 ms debounce on switch 1

// the setup routine runs once when you press reset:
void setup() {   
  Serial.begin(31250);                  //  Set MIDI baud rate:
  selectPatch(INITIAL_PATCH);           // Set inital patch number
  pinMode(SWITCH1,INPUT_PULLUP);        // Open switch is normally pulled high
  pinMode(LED, OUTPUT);                 // initialize the led pin as an output.
  digitalWrite(LED, HIGH);              // led on = initial patch  
}

// the loop routine runs over and over again forever:
void loop() {

  if (bouncer1.update()) {               // returns true if switch1 state changed (on or off)
    if (!bouncer1.read()) {              // if switch is pressed (input low)
      if (patch == INITIAL_PATCH) {      // if current patch = initial patch
        selectPatch(ALT_PATCH);          // swap to alt patch
        patch=ALT_PATCH;                 // remember it
        digitalWrite(LED, LOW);          // led off = alt patch
      }
      else {                             // current patch = alt patch
        selectPatch(INITIAL_PATCH);      // swap to inital patch
        patch=INITIAL_PATCH;             // remember it
        digitalWrite(LED, HIGH);         // led on = inital patch
      }      
    }
  }

}

void selectPatch(int patchNum) {
  Serial.write(0xC0);                    // change patch command
  Serial.write(patchNum-1);              // patch '1' is really zero etc
}

I am going to look at using Exclusive ORs to replace the ‘state’ code and LED flip flopping but for now this works very well. Hook up another switch, bit more code and the prototype will be done.

Total turn around time so far to get to this point (including installing the compiler and research), about an hour!

Makes the iPhone programming look ridiculously hard (still trying to figure out how to fix a memory leak. I know where it is, just not how to fix. very frustrating!).

Categories: Coding, Development Tools Tags: